Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

aggrega serve

aggrega serve uruchamia Aggrega jako długo działającego demona typu compiler-as-a-service na potrzeby integracji z IDE. Komunikuje się za pomocą JSON-RPC 2.0 przez stdin/stdout i przechowuje między żądaniami stan resolvera katalogów, pamięci podręcznej parsowania oraz diagnostyki, dzięki czemu operacje edytora otrzymują informację zwrotną w czasie poniżej sekundy, zamiast ponosić pełny koszt ładowania katalogu przy każdym naciśnięciu klawisza.

Demon jest zwykle uruchamiany jako podproces przez rozszerzenie edytora, a nie ręcznie. Klientem referencyjnym jest rozszerzenie VS Code; inne edytory mogą się zintegrować, posługując się tym samym protokołem.

Protokół

Protokół komunikacyjny to JSON-RPC 2.0 z ramkowaniem Content-Length, w przestrzeni nazw metod aggrega/. Celowo nie jest to Language Server Protocol — Aggrega ma operacje dziedzinowe (zapytanie o graf IR, sygnał unieważnienia pamięci podręcznej), dla których LSP nie ma odpowiednika. Rozszerzenie edytora tłumaczy żądania LSP edytora na te metody aggrega/* i z powrotem; wartości pozycji, zakresu i lokalizacji w kształcie LSP są używane ponownie tam, gdzie pasują.

Dwie metody zachowują standardowe nazwy protokołu z prefiksem $/ zamiast przeniesienia do przestrzeni nazw aggrega/, ponieważ obie dotyczą transportu, nie niosą znaczenia specyficznego dla Aggrega, a klient obsługujący już ten protokół obsługuje je bez żadnych dodatków: $/cancelRequest, która zatrzymuje żądanie, na które klient nie oczekuje już odpowiedzi, oraz $/progress, za pomocą której demon raportuje długą operację w trakcie jej trwania. Obie opisano poniżej.

🔴 Każde poniższe żądanie zawiera workspaceRoot, bezwzględną ścieżkę obszaru roboczego, na którym działa, i nie jest to powtarzane przy każdej metodzie. Trzy żądania go nie zawierają, ponieważ ich przedmiotem nie jest obszar roboczy: aggrega/initialize, aggrega/getSchema i aggrega/scaffoldEntity — z tym że aggrega/scaffoldEntity zapisujące lub wyświetlające listę przykładów gotowych do uruchomienia wskazuje obszar roboczy. Co otrzymuje żądanie, które nie wskazuje żadnego obszaru, opisano w sekcji Każde żądanie wskazuje obszar roboczy, którego dotyczy, a dokąd trafiają wypychane diagnostyki — w sekcji Deklarowanie obszaru roboczego, dla którego mają być wypychane diagnostyki.

Kształty pole po polu są opublikowane jako schemat, a należy je czytać w dokumentacji kształtów komunikacji. Ta strona podaje obiekt parametrów każdej metody, każdy wynik i każdy ładunek powiadomienia — każde pole z typem, informacją, czy jest wymagane, i tym, co przenosi — wraz z trzema właściwościami obowiązującymi w całym interfejsie, a nie dla poszczególnych metod: dwoma polami, które przyjmuje każde żądanie poza zadeklarowanymi przez jego metodę, czyli powyższym workspaceRoot i workDoneToken z sekcji Obserwowanie długiej operacji; tym, że obiekt params zawierający klucz, którego jego metoda nie przyjmuje, jest odrzucany, a odmowa wymienia zbiór akceptowanych kluczy; oraz tym, kiedy nieobecna kolekcja trafia do komunikacji jako null, a nie jako pusta. Strona jest generowana z tego schematu, więc zmienia się wraz ze zmianą kontraktu.

Ta strona opisuje protokół, tamta — kształty, i należy je czytać razem. Tutaj: ramkowanie, do czego służy każda metoda, jak daleko sięga, co zapisuje, jakie odmowy zgłasza i dlaczego, kody błędów i co z każdym zrobić. Tam: co wysłać, klucz po kluczu. Dlatego poniższa lista wymienia każdą metodę i mówi, co oznacza jej wywołanie, a lista pól dla tworzonego żądania znajduje się w dokumentacji obok.

Żądania:

  • aggrega/initialize — uzgadnianie połączenia. Negocjuje kodowanie pozycji (serwer preferuje UTF-8, potem UTF-16, potem UTF-32, a domyślnie używa UTF-16), przyjmuje obszar roboczy deklarowany dla wypychanych diagnostyk i raportuje katalog główny tego obszaru, warstwę konfiguracji, z której pochodzą jego ustawienia, oraz znacznik, który ją wyznaczył. Odpowiedź zawiera też version, wersję odpowiadającego pliku binarnego: tę samą wartość, którą dla tego pliku binarnego raportuje aggrega version. Opisuje ona działający proces, więc gdy plik, z którego uruchomiono demona, zostanie zastąpiony — na przykład przez ponowne zbudowanie pod tą samą ścieżką — version nadal wskazuje działającego demona, podczas gdy odpytanie pliku wskazuje jego zastępcę; należy odczytać ją tutaj, gdy pytanie brzmi, z którą wersją toczy się komunikacja. workspaceRoot jest opcjonalny i deklaruje obszar roboczy, zamiast na nim działać — zob. Deklarowanie obszaru roboczego, dla którego mają być wypychane diagnostyki. Wysłanie capabilities.window.workDoneProgress: true informuje, że klient obsługuje powiadomienia o postępie; pole capabilities.workDoneProgress odpowiedzi to powtarza, a dla klienta, który niczego nie zadeklarował, pole jest nieobecne. Zob. Obserwowanie długiej operacji.
  • aggrega/validate — waliduje zawartość pliku; zwraca diagnostyki. release to ścieżka względna wobec katalogu głównego obszaru roboczego, wskazująca encję Release, względem której odbywa się walidacja — ta sama wartość, którą przyjmuje aggrega/irGraph, i ta sama, którą przyjmuje aggrega build --release uruchomione z katalogu głównego. Jest opcjonalna i określa, jak daleko sięga odpowiedź: po wskazaniu encji Release sprawdzenia, które jej wymagają, są wykonywane względem niej — encja katalogowa jest sprawdzana jako pojedyncza encja w kategoriach tej encji Release, a każdy inny dokument względem domknięcia zależności tej encji Release; po jej pominięciu odpowiedź obejmuje to, czemu dokument może podlegać samodzielnie, i zawiera checked, aby to zaznaczyć. Wartość obecna, lecz nieprawidłowa jest odrzucana w obu przypadkach — ścieżka bezwzględna albo prowadząca poza katalog główny obszaru roboczego jest odrzucana, a nie rozwiązywana. Zob. Walidacja na żywo.
  • aggrega/diagnostics — zwraca ustalenia przechowywane dla pliku. Jeśli w chwili nadejścia żądania trwa walidacja tego samego pliku, odpowiedź czeka na nią i raportuje to, co znalazła, więc odpowiedź nigdy nie jest świadectwem braku problemów dla pliku, w którym demon właśnie je wykrywa. Zob. Pytanie o diagnostyki w trakcie walidacji.
  • aggrega/hover — treść podpowiedzi dla encji na danej pozycji. release jest opcjonalne i daje odpowiedź w kategoriach tej encji Release — zob. Odpowiadanie w kategoriach jednej encji Release.
  • aggrega/completion — kandydaci uzupełniania na danej pozycji. Tam, gdzie kursor wskazuje encję według rodzaju — type komponentu, type dołączenia encji Feature, wartość extends:, implements: encji Recipe lub FeatureRecipe — kandydatami są nazwy tego rodzaju deklarowane przez własne dokumenty obszaru roboczego oraz, w przypadku encji Component lub Feature, także nazwy deklarowane przez skonfigurowane catalog_dirs, każda zaproponowana raz i w kolejności nazw. Obszar roboczy, który pobiera swoje Components i Features z katalogu, otrzymuje więc je w propozycjach, a nie tylko to, co sam utworzył. Recipes i FeatureRecipes, proponowane przy wartości mapowania encji Manifest, pochodzą z własnych dokumentów obszaru roboczego. Encja przechowywana wyłącznie w pamięci podręcznej artefaktów lub w rejestrze nie jest proponowana: odpowiedź na uzupełnianie nigdy niczego nie pobiera. release jest opcjonalne i daje odpowiedź w kategoriach tej encji Release — zob. Odpowiadanie w kategoriach jednej encji Release.
  • aggrega/resolve — rozwiązuje encję, do której odwołuje się dana pozycja (przejście do definicji). release jest opcjonalne i daje odpowiedź w kategoriach tej encji Release — zob. Odpowiadanie w kategoriach jednej encji Release.
  • aggrega/findReferences / aggrega/findImplementations. Każda przyjmuje opcjonalne release i daje odpowiedź w kategoriach tej encji Release — zob. Odpowiadanie w kategoriach jednej encji Release.
  • aggrega/irGraph — skompilowany graf IR dla encji Release, do introspekcji w edytorze. release to ścieżka względna wobec katalogu głównego obszaru roboczego, wskazująca znajdującą się w nim encję Release — ta sama wartość, którą przyjmuje aggrega build --release uruchomione z katalogu głównego. Każda inna postać jest odrzucana standardowym błędem nieprawidłowych parametrów, który wskazuje, co należy wysłać zamiast niej: ścieżka bezwzględna, ścieżka prowadząca poza katalog główny obszaru roboczego — czy to wychodząca z niego w zapisanej postaci, czy prowadząca na zewnątrz przez dowiązanie, do pliku albo do katalogu po drodze — oraz wartość pusta są odrzucane, a nie rozwiązywane, więc żadne żądanie nie raportuje o pliku, którego obszar roboczy nie zawiera. Encja Release, którą nazywa konfiguracja obszaru roboczego, jako build.authoring_release lub jako klucz workspace.releases, należy do obszaru roboczego bez względu na to, gdzie leży jej plik, więc prowadzące do niej dowiązanie wewnątrz obszaru roboczego jest akceptowane, tak jak wymienia ją aggrega/releaseCandidates. Katalog katalogu encji, który czyta Release, a którego nie da się przejść — na przykład taki, który istnieje, ale nie da się go odczytać — jest odrzucany tak, jak odrzuca go aggrega inspect, zanim cokolwiek innego zostanie odczytane: błąd to 1004 entity-not-resolvable, jego komunikatem jest raport, który wiersz poleceń wypisuje dla tego katalogu, w jednym wierszu ([CATALOG_ERROR] <directory>: catalog load: …), i nie powstaje żaden graf z pozostałych katalogów. Katalog wymieniony w konfiguracji obszaru roboczego, który nie jest katalogiem — na przykład w jego miejscu nic nie istnieje — jest odrzucany w ten sam sposób i w tym samym momencie, z 1004 entity-not-resolvable, a jego komunikatem jest odmowa, jaką daje mu każde polecenie, wskazująca wpis, plik konfiguracji i wiersz, które go wymieniają, oraz ustawienie (Where local entities are read from). Katalog katalogu encji zawierający dowiązanie prowadzące poza katalog, w którym muszą pozostać jego odczyty — dokument lub katalog dowiązany z innego miejsca, wewnątrz katalogu katalogu encji w obszarze roboczym albo wewnątrz takiego, który konfiguracja nazywa poza nim — jest odrzucany w ten sam sposób i w tym samym momencie, z 1004 i własnym zdaniem danego warunku, które wskazuje dowiązanie i miejsce, do którego prowadzi: przez takie dowiązanie nic nie jest odczytywane, a graf powstały bez niego mógłby w jego miejsce rozwiązać inną encję o tej samej nazwie. Tak samo jest z dowiązaniem prowadzącym na zewnątrz spośród dokumentów obok encji Release, gdy Release nazywa swoją encję Aggregate lub Manifest przez tożsamość. Plik, który Release, jej Manifest lub rozszerzana przez nią encja Release nazywa ścieżką — aggregate:, manifest:, extends: lub $import: parametrów — i który prowadzi poza obszar roboczy, w zapisanej postaci lub przez dowiązanie, jest odrzucany z własnym zdaniem danego warunku (fatal-halts.md §„A reference to another file leads out of the directory it must stay inside (Odwołanie do innego pliku prowadzi poza katalog, w którym musi pozostać)”), przy czym dane błędu umieszczają go na kluczu w encji Release, który doprowadził do pliku, i nic nie jest z tego pliku odczytywane; encja Release, którą konfiguracja nazywa poza obszarem roboczym, jest w ten sam sposób ograniczona do zawierającego ją katalogu, więc ścieżka zapisana przez nią lub przez encję Release z jej łańcucha, która opuszcza ten katalog, również jest odrzucana. Należy pamiętać, że aggrega/releaseCandidates odpowiada ścieżkami bezwzględnymi, więc klient zasilający jedną powierzchnię drugą dokonuje konwersji między nimi. To, że ten parametr odrzuca zapis akceptowany przez parametry file i uri dotyczące dokumentu, jest zamierzone, a Which spellings a parameter you send accepts wyjaśnia, co o tym decyduje. Graf ukrywa każdą wartość, którą autor zadeklarował jako wrażliwą, dokładnie tak, jak ukrywa ją --ir-graph w wierszu poleceń: każda jest zastępowana znacznikiem opisanym w aggrega-inspect „Machine-readable output”, a wszystko inne jest przekazywane tak, jak zapisał to kompilator. unredacted: true żąda tych wartości jawnie — to protokołowy odpowiednik --unredacted z wiersza poleceń i jedyny sposób, by o nie poprosić; gdy go brak lub ma wartość false, odpowiedź je ukrywa. Wszystko, do czego trafi odpowiedź, zawiera wtedy te wartości jawnie, więc klient prosi o nie tylko tam, gdzie poprosiła o nie osoba, która z niego korzysta.
  • aggrega/build — kompiluje encję Release i zapisuje jej artefakty w katalogu wyjściowym obszaru roboczego, tym samym, do którego zapisuje aggrega build uruchomione z katalogu głównego obszaru roboczego. release podlega temu samemu kontraktowi co powyżej. Renderowanie odbywa się z włączonymi wszystkimi bramkami, więc rozbieżność, na której zatrzymałaby się kompilacja z wiersza poleceń, zatrzymuje także tutaj. Katalog katalogu encji, który czyta Release i którego nie da się przejść — na przykład istniejący, ale nieczytelny — jest odrzucany tak, jak odrzuca go aggrega build, zanim cokolwiek zostanie zapisane: bez żadnego artefaktu i bez pliku blokady, gdy ustawiono autoPull. Tak samo jest z katalogiem wymienionym w konfiguracji obszaru roboczego, który nie jest katalogiem — w słowach, w jakich odrzuca go aggrega build (Skąd czytane są encje lokalne). Odmowa jest taka sama jak ta, którą daje aggrega/irGraph dla tego samego katalogu: 1004 entity-not-resolvable z raportem wiersza poleceń w jednym wierszu, a dowiązanie wyprowadzające poza zakres odczytu katalogu encji albo poza dokumenty obok encji Release jest odrzucane tak, jak odrzuca je aggrega/irGraph, bez zapisania czegokolwiek. Odpowiedź podaje outputDirectory, do którego zapisano, oraz zapisane files, każdy względem tego katalogu i posortowane, wraz z wszelkimi notices zgłoszonymi podczas przebiegu; ustalenia zawierające pozycję w dokumencie trafiają natomiast do aggrega/publishDiagnostics. Na encję Release, która odmawia podczas renderowania, odpowiedzią jest ta odmowa w słowach kompilatora, ze wszystkimi przyczynami, a odmowa jest publikowana tam, gdzie wskazuje — zob. Odmowa zgłoszona podczas renderowania. Gdy ustawiono autoPull, odpowiedź zawiera także dependencyResolution, ten sam raport, którym odpowiada aggrega/resolveDependencies, więc klient, który uzupełnił zależności w ramach kompilacji, odczytuje, co przypięto, bez ponownego pytania — a także, skąd rozwiązywanie w tej kompilacji wzięło każde odwołanie, co jest faktem o danym przebiegu, którego plik blokady nie zapisuje. Każde powiadomienie zawiera class powierzchni, która je zgłosiła — deprecation, catalog, catalog-lint, extends, release-composition albo dependency-resolution dla wiersza zgłoszonego przez opisane niżej rozwiązywanie zależności — oraz puste class, gdy demon nie ma nazwy dla tej powierzchni; klient wyświetla wtedy samo text, zamiast zgadywać najbliższe dopasowanie. Pliki, które zapis znajduje w katalogu wyjściowym lub w katalogu pod nim, do którego zapisał plik albo przez który przeszedł, a których ta kompilacja nie zapisała, pozostają na miejscu i są wymieniane w jednym powiadomieniu po powiadomieniach samego przebiegu, z pustym class, w zdaniu, w którym aggrega build wypisuje swoje ostrzeżenie — zob. Pliki, których kompilacja nie zapisała; files nigdy ich nie wymienia. outputParent określa, gdzie w obszarze roboczym trafiają artefakty, a jego nazwa oddaje całe jego znaczenie: jest to katalog, wewnątrz którego tworzony jest katalog wyjściowy, więc wysłanie docs zapisuje artefakty do docs/dist, a nie do samego docs — dokładnie to, co daje kompilacja uruchomiona w docs w terminalu. Jeśli go pominąć, kompilacja zapisuje tam, gdzie zapisuje kompilacja uruchomiona w katalogu głównym obszaru roboczego. Rozumie się go inaczej niż outputDir, który przyjmują inne zapisujące żądania tutaj, i jest to celowe: tamte wskazują katalog, do którego się zapisuje, ten wskazuje katalog nadrzędny tego katalogu, a obie mają różne nazwy, bo są różnymi rzeczami. Nadal jest to miejsce docelowe w obszarze roboczym, więc wartość bezwzględna, wartość wychodząca poza katalog główny oraz wartość prowadząca poza niego przez dowiązanie — dowiązany katalog poza katalogiem głównym albo jeszcze nieutworzony katalog pod takim — są odrzucane, a nie rozwiązywane. Katalog wyjściowy tworzony w jego wnętrzu i każdy plik, który kompilacja tam zapisuje, również muszą pozostać w obszarze roboczym: gdy któryś z nich prowadzi poza obszar roboczy przez dowiązanie, kompilacja jest odrzucana z 1004 i własnym zdaniem tego warunku, wskazującym dowiązanie i miejsce, do którego prowadzi, a nic nie jest czyszczone ani zapisywane. autoPull rozwiązuje zależności encji Release przed renderowaniem — to samo rozwiązywanie, które wykonuje aggrega/resolveDependencies — i jest wyłączone, chyba że żądanie o nie poprosi, zgodnie z domyślnym ustawieniem wiersza poleceń; bez niego Release bez pliku blokady jest odrzucany z błędem braku pliku blokady, wskazującym, co należy uruchomić. Przy ustawionym autoPull to żądanie łączy się z rejestrami i zapisuje plik blokady — zob. Łączenie z rejestrem i zapisywanie. Żądanie, które najpierw rozwiązuje zależności, nadal renderuje Release raz: ustalenie, które zdalne odwołania konsumuje Release, samo jest renderowaniem, więc rozwiązywanie już wyrenderowało to, czego dotyczy kompilacja, a kompilacja otrzymuje odpowiedź z tego renderowania, zamiast je powtarzać. policyInput wskazuje katalog w obszarze roboczym, względny wobec jego katalogu głównego, do którego kompilacja zapisuje także ładunek przekazywany przez każdą rolę zarządczą dołączonej tam wtyczce — pliki, które zapisuje aggrega build --policy-input, pod tymi samymi nazwami — niezależnie od tego, czy kompilacja się zakończy, czy zatrzyma; notices odpowiedzi podają wtedy, ile plików zapisano, i wskazują każdą rolę, dla której nie zapisano żadnego pliku, z pustym class. Przy żądaniu zakończonym błędem zapisane pliki pozostają na dysku, a tego zestawienia nie ma w odpowiedzi: koperta błędu zawiera jedynie odmowę. Jest to miejsce docelowe, więc wartość bezwzględna lub wartość wychodząca poza obszar roboczy jest odrzucana, zanim cokolwiek zostanie uruchomione.
  • aggrega/buildPreview — zgłasza, co zapisałaby kompilacja encji Release, nie zapisując niczego. release podlega temu samemu kontraktowi co powyżej. Wykonuje te same obliczenia co aggrega/build, przy tych samych bramkach, więc Release albo zostałby odrzucony przez oba, albo jest zgłaszany przez oba — i dlatego wybór między nimi dotyczy wyniku, a nie rygorystyczności. Katalog katalogu encji, który czyta Release i którego nie da się przejść albo który zawiera dowiązanie wyprowadzające poza katalog, w którym muszą pozostać jego odczyty, jest odrzucany w ten sam sposób, zanim cokolwiek zostanie wyrenderowane, podobnie jak katalog wymieniony w konfiguracji obszaru roboczego, który nie jest katalogiem, tak jak w aggrega/build. Odpowiedź zawiera files, posortowane nazwy względne wobec katalogu wyjściowego, które wygenerowałaby kompilacja, wraz z wszelkimi notices; nie ma outputDirectory, ponieważ nigdzie niczego nie zapisano, więc nie ma czego wskazać. Release, który odmawia podczas renderowania, otrzymuje odpowiedź i jest publikowany dokładnie tak, jak robi to aggrega/build. Żądanie odrzuca autoPull z błędem invalid-params wskazującym, co wysłać zamiast tego: uzupełnianie zależności zapisuje plik blokady, a to żądanie nie zapisuje pliku blokady. Nie łączy się z żadnym rejestrem. policyInput to jedyny zapis, jaki wykonuje, i tylko wtedy, gdy zostanie wysłany: zapisuje ładunki zarządcze do tego katalogu dokładnie tak jak aggrega/build — pliki, które zapisuje aggrega build --dry-run --policy-input — nie naruszając katalogu wyjściowego ani pliku blokady, z tym samym zestawieniem w notices i tym samym ograniczeniem: przy żądaniu zakończonym błędem zapisane pliki pozostają na dysku, a zestawienia nie ma w odpowiedzi.
  • aggrega/resolveDependencies — rozwiązuje zależności katalogowe i źródłowe encji Release do pamięci podręcznej, przypina zewnętrzne dane wejściowe, które konsumuje jej renderowanie, w magazynie adresowanym treścią i zapisuje jej plik blokady. release to ścieżka względna wobec katalogu głównego obszaru roboczego, ta sama wartość, którą przyjmuje aggrega/irGraph, odrzucana w tych samych postaciach. upgrade odrzuca zapisane przypięcia i rozwiązuje ponownie, podnosząc każdą zależność do najwyższej dostępnej wersji; targets zawęża to do wskazanych referencji encji, zachowując wszystkie pozostałe przypięcia. verify porównuje zapisane rozwiązanie z tym, które to żądanie wykonałoby bez niego, honorując zapisane przypięcia w ten sam sposób, i nie zapisuje pliku blokady, rekordu zaufania wtyczek ani entity.lock — pamięć podręczna jest odczytywana i wypełniana tak, jak byłaby bez niego — odpowiadając verified: true oraz toolchain zapisanym w pliku blokady. verify jest odrzucane jako nieprawidłowe parametry obok upgrade, obok targets i obok pinSources niezależnie od jego wartości, zanim cokolwiek zostanie rozwiązane lub zgłoszony zostanie jakikolwiek postęp: aktualizacja porzuca przypięcia, które weryfikacja ma honorować, wskazane cele są ponownie rozwiązywane tylko przez aktualizację, a pinSources decyduje, czy rozwiązanie zapisuje przypięcia, których brakuje w entity.lock, czy z ich powodu odmawia — żadnego z tych działań nie wykonuje porównanie, które nie zapisuje entity.lock. Wiersz poleceń i narzędzie asystenta odrzucają te same pary. Odpowiedź wskazuje lockfile, który zapisano lub z którym porównano, oraz każdą przypiętą referencję w entities, libraries i plugins, przy czym każdy wpis zawiera version, do której go rozwiązano, i swoje source — skąd to uruchomienie pobrało referencję, słowem, które aggrega pull --detail wypisuje dla tego samego rozwiązania: fetched-fresh, cache-reuse, local, in-binary lub external — obok sourceArtifacts, trustedPlugins, externalInputs — ile zewnętrznych danych wejściowych przypina plik blokady po zakończeniu uruchomienia, licząc zarówno przeniesione, jak i odkryte w tym uruchomieniu — oraz wszelkich notices zgłoszonych przez rozwiązanie. 🔴 Pomyślna odpowiedź sama w sobie nie oznacza, że przypinanie zewnętrznych danych wejściowych jest kompletne. Jeśli uruchomienie przypięło każdą zależność, ale nie zdołało ustalić do końca, które zewnętrzne dane wejściowe konsumuje encja Release, odpowiada polem incompleteExternalInputs mówiącym, co przerwało wykrywanie, i nadal odpowiada sukcesem — przypięcia zależności są kompletne i zapisane na dysku, więc zgłoszenie całego żądania jako nieudanego kazałoby powtórzyć pracę, która jest już poprawna. Należy odczytać to pole, zanim uzna się plik blokady za w pełni przypięty: jest ono nieobecne, gdy nic nie pozostało nieodkryte, więc jego obecność jest sygnałem. Nie ma parametru katalogu katalogów: stos wyszukiwania to ten, który konfiguruje obszar roboczy. Jest to jedyne w sesji żądanie przypinania dla encji Release i to w nim przypinane są także zewnętrzne dane wejściowe — to, które adresy URL konsumuje renderowanie, wynika z tego, co renderuje, więc to żądanie renderuje encję Release, aby to ustalić, a żądanie kompilacji jest następnie obsługiwane na podstawie tego, co zapisało. Encja Recipe lub FeatureRecipe budowana przez Release, której entity.lock nie zapisuje przypięcia dla danych wejściowych odczytywanych przez encję, powoduje odrzucenie żądania ze wskazaniem aggrega pin i każdego niezapisanego wejścia; pinSources: true uruchamia zamiast tego ten krok przypinania dla tych encji, zapisując entity.lock obok każdej — ten sam krok, który wykonuje aggrega/pin, zapisujący te same bajty. Gdy pinSources jest nieobecne, podąża za ustawieniem pin_sources_at_pull obszaru roboczego; gdy jest wysłane, nadpisuje to ustawienie w obu kierunkach, więc false odmawia nawet w obszarze roboczym skonfigurowanym do przypinania. To żądanie łączy się z rejestrami i zapisuje — zob. Łączenie się z rejestrem i zapisywanie.
  • aggrega/pin — zapisuje w entity.lock obok encji Recipe lub FeatureRecipe przypięcie treści dla każdego wejścia, które encja odczytuje spoza własnego dokumentu: zdalnego źródła, którego współrzędne są zapisane w całości, pliku importowanego przez wpis artefaktów oraz każdego pliku, który lokalne źródło wnosi do zawartości publikacji encji. Jest to ten sam krok, który aggrega pin wykonuje w terminalu, i zapisuje te same bajty. entity jest wymagane i jest ścieżką względną wobec katalogu głównego obszaru roboczego wskazującą dokument encji, odrzucaną w tych samych trzech postaciach co release. Nie wskazuje się encji Release: zdalne źródło, którego współrzędne nie zawierają szablonu, wskazuje jeden artefakt dla każdej encji Release używającej tej encji, więc do jego przypięcia nie jest potrzebne nic, co dostarcza Release, natomiast zdalne źródło, którego współrzędne pochodzą z szablonu, jest przypinane osobno dla każdej encji Release przez aggrega/resolveDependencies; lokalne źródło zapisane jako szablon wnosi każdy plik z katalogu encji i każdy z nich jest przypinany tutaj. dryRun rozwiązuje dane wejściowe i odpowiada blokadą, którą krok by zapisał, jako content, nie zapisując niczego obok encji; pamięć podręczna treści nadal się wypełnia. Odpowiedź zawiera entity, kind, name i pinnable — false dla rodzaju, który nie odczytuje niczego, co zapisuje blokada; wtedy niczego obok encji nie zmieniono, a wszystkie pozostałe pola są nieobecne — a w przeciwnym razie zapisany lock, changed (false, gdy blokada zawierała już każde przypięcie i pozostała identyczna co do bajtu), removed, gdy encja nie odczytuje już niczego, co zapisuje blokada, i jej blokadę usunięto, oraz pins, jeden wpis na klasę przypięć z liczbą przechowywaną w blokadzie. Sam plik encji nigdy nie jest zapisywany. To żądanie zapisuje obok encji, wewnątrz obszaru roboczego, i łączy się z hostami wskazanymi w źródłach encji — zob. Łączenie się z rejestrem i zapisywanie.
  • aggrega/cacheStatus — co zawierają pamięci podręczne na dysku: jeden wpis na element w pamięci podręcznej z jego rozmiarem i, jeśli go ma, skrótem treści, pogrupowane według klas. Przyjmuje obszar roboczy i nic więcej. Każda klasa zawiera reach — workspace dla pamięci podręcznej artefaktów w katalogu pamięci podręcznej tego obszaru roboczego, machine dla magazynów skompilowanych modułów, opisów wtyczek i pakietów dokumentacji współdzielonych przez wszystkie projekty na maszynie — a scope bezpośrednio wskazuje klasy obejmujące całą maszynę. Niczego nie zapisuje. Zob. Łączenie się z rejestrem i zapisywanie, aby dowiedzieć się, dlaczego zasięg występuje w odpowiedzi, która niczego nie zmienia.
  • aggrega/cachePrune, aggrega/cacheEvict, aggrega/cacheClear — odzyskują miejsce zajmowane przez treść w pamięci podręcznej. Przycinanie usuwa to, do czego nie odwołuje się żaden plik blokady obszaru roboczego; eksmisja przycina magazyn skompilowanych modułów do maxSize, ilości bajtów zapisanej tak jak w wierszu poleceń (5GiB, 512MiB lub liczba bajtów); czyszczenie usuwa całą zawartość każdej pamięci podręcznej, do której odwołuje się ta sesja. Każda odpowiedź wskazuje, co usunięto, przy czym każde usunięcie zawiera reach klasy, z której pochodzi, i każda zawiera scope. Każda odpowiedź wskazuje też, co pozostawiono, ponieważ inny proces miał to otwarte — Windows odmawia usunięcia otwartego pliku, a operacja kontynuuje z resztą zamiast kończyć się błędem: przycinanie lub eksmisja wymienia te wpisy w heldOpen, a czyszczenie podaje dla każdej opróżnionej pamięci podręcznej liczbę pozostawionych plików w heldOpenFiles i ich rozmiar w heldOpenBytes. W pozostałych przypadkach lista jest pusta, a liczniki wynoszą zero, a późniejsze uruchomienie może odzyskać to, co pozostało. Te żądania sięgają poza obszar roboczy — zob. Łączenie się z rejestrem i zapisywanie.
  • aggrega/registryList — rejestry, z którymi ten obszar roboczy jest skonfigurowany do łączenia się: host każdego wpisu, opcjonalny alias, informacja, czy jest domyślny, jego stanowisko zaufania w postaci odrębnych pól oraz informacja, czy istnieje poświadczenie dla tego hosta. Przyjmuje obszar roboczy i nic więcej. Nie kontaktuje się z żadnym rejestrem. Stan poświadczenia informuje wyłącznie o obecności — nigdy o samym poświadczeniu, nigdy o jego postaci i nigdy o tym, czy rejestr by je zaakceptował, co wymagałoby komunikacji sieciowej, której listowanie nie wykonuje — i jest odczytywany z magazynu poświadczeń obejmującego całą maszynę, co wprost stwierdza credentialStateIsMachineWide.
  • aggrega/search — przeszukuje lokalny indeks skonfigurowanych rejestrów. Każde pole zawęża wyniki i każde jest opcjonalne, więc pusty obiekt parametrów zwraca wszystko, co zawiera indeks. Żadne połączenie sieciowe nie jest nawiązywane: indeks to migawka offline zapisana we własnym katalogu pamięci podręcznej tego obszaru roboczego. Podawana wersja to ta, którą wybrałoby rozwiązywanie zależności — wersja, której wycofanie nosi podpis zaufany przez ten obszar roboczy, jest wykluczana i wymieniana w retracted — a odpowiedź zawiera informację o własnym pochodzeniu: indexes podaje wiek migawki każdego przeszukanego rejestru, stale oznacza migawkę wartą odświeżenia, a missingIndexHosts wymienia skonfigurowane rejestry bez lokalnego indeksu, których zawartości w związku z tym brak w odpowiedzi.
  • aggrega/registryAdd — rejestruje rejestr i jego politykę zaufania do podpisów. host jest wymagany; wszystko inne kształtuje politykę lub cel zapisu. keyPath i trustedRoot wskazują pliki: wartość bezwzględna — na przykład plik wybrany w oknie dialogowym — jest odczytywana tam, gdzie wskazuje; względna wskazuje plik wewnątrz obszaru roboczego, rozwiązywany względem katalogu głównego obszaru roboczego, a nie katalogu, w którym działa demon, a wartość wychodząca poza katalog główny lub prowadząca poza niego przez dowiązanie jest odrzucana z błędem nieprawidłowych parametrów, zanim cokolwiek zostanie odczytane lub zapisane. Względny trustedRoot jest zapisywany jako plik, który wskazuje w obszarze roboczym, więc wpis wskazuje ten plik niezależnie od katalogu, w którym zostanie uruchomiona późniejsza weryfikacja. fetchTrust przy braku klucza przyjmuje domyślnie wartość true, zgodnie z wierszem poleceń, i przy pierwszym kontakcie pobiera politykę ogłaszaną przez sam rejestr; trust w odpowiedzi mówi, co się stało — polityka została przypięta, rejestr żadnej nie ogłosił (a gdy obok jest unreachable, nie udało się z nim w ogóle połączyć), w jej miejsce przypięto wbudowaną bazową politykę oficjalnego huba albo nie podjęto próby pobrania. Rejestracja jest tą samą, którą wykonuje aggrega registry add: to samo pobranie przy tej samej polityce sieciowej, zapisujące ten sam wpis bajt w bajt. W obszarze roboczym offline pobranie jest odrzucane, zanim nastąpi jakiekolwiek połączenie, więc rejestr nigdy nie jest odpytywany, a rejestr inny niż oficjalny hub jest odrzucany, chyba że żądanie podaje identities lub keyPath, które rejestrują dokładnie to, co wysłano, bez pobierania: komunikat błędu to zdanie wypisywane przez wiersz poleceń, poprzedzone krótkim kodem warunku E0310 — tak jak komunikat każdej odmowy tego żądania wskazującej warunek zaczyna się od jego krótkiego kodu — i nic nie jest zapisywane. Oficjalny hub jest nadal zapisywany z wbudowaną polityką bazową, a odpowiedź zawiera trust.baseline równe true i trust.reason informujące, że hub nie został zapytany o politykę zaufania, ponieważ obszar roboczy jest offline — tym samym powodem rozpoczyna się komunikat wiersza poleceń — i nie zawiera notAdvertised, ponieważ hub nigdy nie został zapytany. Domyślnie zapisuje to konfigurację globalną — zob. Dostęp do rejestru i zapis.
  • aggrega/registryRemove — usuwa wpis rejestru wskazany przez host lub przyjazny alias. Token, który niczego nie pasuje, jest odrzucany, zamiast zwracać sukces przy niezmienionej konfiguracji. Domyślnie zapisuje to konfigurację globalną — zob. Dostęp do rejestru i zapis.
  • aggrega/logout — usuwa zapisane poświadczenie dla rejestru; to samo usunięcie wykonuje aggrega logout w terminalu. registry jest wymagany i wskazuje host rejestru w postaci użytej przy uwierzytelnianiu; nie ma tu przyjaznego aliasu do rozwiązania, ponieważ magazyn poświadczeń jest indeksowany adresem, wobec którego klient się uwierzytelnia, a nie czymkolwiek, co nazywa konfiguracja, więc host nieskonfigurowany w żadnym obszarze roboczym może nadal mieć poświadczenie, które można usunąć. Host, dla którego magazyn nie przechowuje poświadczenia, jest usuwany pomyślnie i nic nie jest przepisywane — wywołujący, który zażądał, by host nie miał poświadczenia, otrzymał to, o co prosił, więc jest to odpowiedź, a nie błąd, i tak samo postępuje polecenie terminalowe. Odpowiedź zawiera registry i scope. Nie zawiera żadnej części poświadczenia w żadnej postaci i nie informuje, czy poświadczenie w ogóle istniało: ustalenie tego wymagałoby drugiego odczytu magazynu, o który nikt nie prosił, więc gdy chodzi o obecność, należy użyć aggrega/registryList. Żaden rejestr nie jest odpytywany — usunięcie zapisanego poświadczenia jest operacją lokalną, a to, czy rejestr przyjąłby poświadczenie, nie jest sprawdzane. Zmienia to magazyn poświadczeń współdzielony przez wszystkie projekty na maszynie — zob. Dostęp do rejestru i zapis.
  • aggrega/registryUpdate — odświeża lokalny przeszukiwalny indeks odczytywany przez aggrega/search. Brak registry odświeża wszystkie skonfigurowane rejestry; wskazanie jednego odświeża tylko ten rejestr. upgrade ponownie odczytuje w całości każde repozytorium, nie porównując niczego z już zapisanym indeksem; odświeżanie bez niego i tak ponownie odczytuje wszystko, co się zmieniło. Odpowiedź zawiera liczbę rekordów każdego hosta, repozytoria, których nie udało się odczytać — każde z reason, zaczynającym się od rodzaju ostatniego niepowodzenia odczytu, jeśli jest znany — readsRetried, czyli liczbę odczytów, które rejestr po drodze odrzucił lub przerwał i o które poproszono ponownie, każdy liczony raz, z zerem włącznie, napotkane znaczniki wycofania, error hosta, który zawiódł — z unreachable obok, gdy nie udało się połączyć z rejestrem — oraz indexRoot, katalog we własnej pamięci podręcznej tego obszaru roboczego, do którego zapisano indeksy. Kontaktuje się to z każdym odświeżanym rejestrem — zob. Dostęp do rejestru i zapis.
  • aggrega/publishEntity — pakuje encję katalogu i publikuje ją w rejestrze. entity to ścieżka względna wobec katalogu głównego obszaru roboczego, wskazująca dokument do opublikowania, odrzucana w tych samych trzech przypadkach co release — gdy jej brak, gdy jest bezwzględna lub gdy rozwiązuje się poza katalogiem głównym. Encja Plugin wymaga też plugin, ścieżki tego samego rodzaju, wskazującej plik wykonywalny publikowany wewnątrz własnego manifestu encji. registry to miejsce docelowe, domyślnie rejestr skonfigurowany w obszarze roboczym. dryRun oblicza pakiet i skrót, pod którym trafiłaby jego publikacja, i nie łączy się z żadnym rejestrem. Pominięcie sign oznacza zastosowanie własnej polityki rejestru docelowego, tak jak robi to wiersz poleceń przy braku flagi, a jego wysłanie jest wyborem wywołującego — i żadne z nich nie łagodzi odmowy, ponieważ polityka rejestru lub obszaru roboczego wymagająca podpisu odrzuca niepodpisaną publikację niezależnie od wartości pola. pinSources: true uruchamia krok przypinania autora encji na encji przed jej spakowaniem, więc plik entity.lock zapisany przez ten krok obok niej jest częścią publikacji — to ten sam krok, który uruchamia aggrega/pin. Krok ten wykonuje się przed każdą odmową oceniającą treść encji — polityką podpisywania, ochroną niezmienności — więc publikacja odrzucona na tym etapie i tak pozostawia zapisany plik blokady; odmowa dotycząca samego żądania, taka jak obszar roboczy w trybie offline lub brak miejsca docelowego, następuje wcześniej i niczego nie przypina, podobnie jak odmowa dla encji współdzielącej katalog z inną encją, w którym krok nie może zapisać pliku blokady. Gdy pole jest nieobecne, obowiązuje ustawienie pin_sources_at_push obszaru roboczego; gdy jest wysłane, nadpisuje to ustawienie w obu kierunkach. W trybie dryRun krok zgłasza plik blokady, który by zapisał, i niczego nie zapisuje. Publikacja, która nie uruchamia tego kroku, odrzuca encję Recipe lub FeatureRecipe, której entity.lock nie zawiera przypięcia dla odczytywanego wejścia, lub takiej, której wejście przestało mu odpowiadać, zanim cokolwiek zostanie spakowane — również w trybie dryRun — wskazując aggrega pin, pinSources i pin_sources_at_push; jest to ta sama odmowa, którą zgłasza aggrega/resolveDependencies dla tego samego pliku blokady. Odpowiedź zawiera reference, tag, kind, mediaType, parę size, opublikowany digest — w trybie dryRun skrót, pod którym trafiłaby publikacja, ten sam, który wypisuje aggrega push --dry-run — signed, alreadyPublished, dryRun i reach; pin — tę samą odpowiedź, którą daje aggrega/pin — jeśli krok został wykonany; oraz wholeDirectorySource, jeśli lokalne źródło encji jest zapisane jako szablon, wskazując to źródło w postaci, w jakiej je napisano. Takie źródło wybiera swój katalog dopiero wtedy, gdy encja Release wypełni szablon, więc publikacja zawiera każdy plik w katalogu encji, a nie tylko pliki, które encja wskazuje, i to pole pozwala wywołującemu dowiedzieć się, że tak się stało — również przy przebiegu próbnym. Zawiera też windowsUnusableEntries, jeśli archiwum przenoszone przez publikację zawiera wpisy, których Windows nie może przechować w zapisanej postaci — ścieżkę z członem nazwanym jak urządzenie, np. CON, AUX lub NUL, w dowolnej wielkości liter i z dowolnym rozszerzeniem, albo z członem kończącym się kropką lub spacją — wymieniając każdy z nich, najpierw nazwę pliku samego dokumentu encji, a potem pliki, które zawiera; pole jest nieobecne, gdy takich wpisów nie ma, co obejmuje encję publikowaną jako sam dokument. aggrega uruchomiona w systemie Windows odmawia rozpakowania takiego wpisu, więc obszar roboczy w systemie Windows nie może użyć tej wersji. Są to wpisy, przed którymi ostrzega aggrega push, a żądanie, które poprosiło o raportowanie, odczytuje te same wiersze ostrzeżeń wśród postępu publikacji; żadne z nich niczego nie odrzuca, więc publikacja przebiega lub zostaje odrzucona dokładnie tak, jak bez nich, również w trybie dryRun. Zapisuje to do rejestru i sięga poza tę maszynę, a z krokiem przypinania zapisuje też obok encji — zob. Łączenie z rejestrem i zapis.
  • aggrega/publishArtifact — publikuje samodzielny artefakt danych, np. pakiet dokumentacji. file to ścieżka względna wobec katalogu głównego obszaru roboczego, podlegająca tym samym zasadom, a jej bajty są publikowane bez zmian: żadna koperta encji nie jest analizowana i żaden rodzaj nie decyduje o obsłudze. name i tag określają, pod czym artefakt jest publikowany, i oba są wymagane. mediaType domyślnie ma typ pakietu dokumentacji. Odpowiedź zawiera reference, tag, mediaType, parę size, opublikowany digest, alreadyPublished, dryRun i reach. Niczego nie podpisuje — opublikowany artefakt podpisuje się później przez odwołanie za pomocą aggrega/signArtifacts, które potrzebuje tylko odwołania zgłoszonego w tej odpowiedzi. Zapisuje to do rejestru i sięga poza tę maszynę — zob. Łączenie z rejestrem i zapis.
  • aggrega/signArtifacts — podpisuje już opublikowane artefakty i dołącza każdy podpis. references zawiera jeden lub więcej adresów rejestru, a nie ścieżek, więc nie podlegają zasadom ścieżek względnych wobec obszaru roboczego; pusta lista lub pusty wpis na niej są odrzucane. Jedna tożsamość obsługuje całą partię i jest rozwiązywana przed podpisaniem jakiegokolwiek odwołania, więc partia bez żadnych dostępnych poświadczeń zostaje odrzucona na początku, a nie w trakcie. Tak samo partia, której odwołania wymagałyby różnych poświadczeń: żądanie nie wskazuje klucza, więc oznacza to, że konfiguracja obszaru roboczego wskazuje posiadany klucz dla rejestru jednego odwołania, a dla rejestru drugiego żaden lub inny klucz — nic nie zostaje podpisane, a odmowa wymienia rejestry po każdej stronie, jak opisuje References signed together need different signing credentials (Odwołania podpisywane razem wymagają różnych poświadczeń podpisu). Podpisanie odwołania, pod którym nic nie opublikowano, jest odrzucane, a nie dołączane do niczego, a odwołanie mające już podpis weryfikowany przez politykę zaufania jego rejestru pozostaje bez zmian i jest liczone jako podpisane, jak opisuje aggrega sign. jobs, opcjonalne, określa, ile odwołań jest podpisywanych jednocześnie: gdy go brak, są one podpisywane jedno po drugim, a wartość mniejsza niż 1 jest odrzucana błędem invalid-params, zanim zostanie odczytane jakiekolwiek odwołanie. Każde odwołanie jest nadal podpisywane dokładnie tak, jak byłoby podpisane samodzielnie, jak opisuje aggrega sign, a zarówno postęp zgłaszany przez żądanie, jak i odpowiedź zachowują kolejność, w jakiej podano odwołania. Odpowiedź zawiera signed, w którym każdy wpis wskazuje reference i opublikowany digest, którego dotyczy podpis, obok reach; partia, w której którekolwiek odwołanie zawiodło, otrzymuje odpowiedź w postaci błędu wymieniającego każde z nich, a nie wyniku z krótszą listą. Zapisuje to do rejestru i sięga poza tę maszynę — zob. Łączenie z rejestrem i zapis.
  • aggrega/deprecateArtifact — dołącza podpisany znacznik wycofania do już opublikowanego artefaktu. Należy wysłać albo pojedyncze reference z severity i reason, albo from wskazujące plik partii względny wobec katalogu głównego obszaru roboczego — wysłanie obu jest odrzucane. Pola treści są wymagane, a nie pobierane interaktywnie: nikt nie obserwuje tego strumienia, więc żądanie bez któregoś z nich jest odrzucane ze wskazaniem, co należy wysłać. Należą one wyłącznie do pojedynczego reference: plik partii zawiera treść każdego znacznika we własnych wpisach, więc severity, reason, replacement lub message wysłane obok from są odrzucane jako nieprawidłowy parametr ze wskazaniem każdego wysłanego pola, zamiast być ignorowane. Obowiązują tu te same dane wejściowe dla podpisywania bezkluczowego co w dwóch żądaniach podpisywania, ponieważ znacznik jest podpisywany własnym skrótem, a wpisy pliku partii podlegają jednemu poświadczeniu dokładnie tak jak odwołania partii podpisywania. Odpowiedź zawiera marked, w którym każdy wpis wskazuje wycofane reference, jego severity, znacznik czasu issuedOn i własny digest manifestu znacznika — znacznik jest dołączany jako nieotagowany referrer artefaktu, który wycofuje, więc nic innego go nie adresuje — obok reach. Zapisuje to do rejestru i sięga poza tę maszynę — zob. Łączenie z rejestrem i zapis.
  • aggrega/catalogIndex — indeks encji: kind, name, apiVersion, description, labels, plik źródłowy i origin każdej encji w obszarze roboczym wskazanym w żądaniu. Przyjmuje obszar roboczy i opcjonalnie release: zbiór jest własnością danego katalogu głównego obszaru roboczego i skonfigurowanych w nim katalogów katalogu encji albo, z release, katalogów, które konfiguracja przypisuje encji Release — zob. Odpowiadanie w kategoriach jednej encji Release. Obejmuje oba miejsca, z których pochodzi encja — dokumenty Aggrega w katalogu głównym obszaru roboczego oraz Features dostarczane przez skonfigurowane katalogi katalogu encji — ponieważ jest to powierzchnia, z którą klient łączy dane, gdy potrzebuje pól opisowych encji, a indeks znający tylko jedno z tych miejsc pozostawiłby część każdej listy kandydatów nierozwiązywalną. Dokument obszaru roboczego jest uznawany za encję, gdy deklaruje zarówno kind:, jak i metadata.name i nie deklaruje apiVersion należącego do grupy innego projektu, dzięki czemu YAML, który przypadkiem znajduje się w drzewie — plik wartości wykresu, konfiguracja CI, wyrenderowany manifest Kubernetes — jest pomijany, a nie wymieniany. Dokument, który w ogóle nie deklaruje apiVersion, jest zgłaszany: jest to dokument Aggrega z brakującym polem, a jego obecność na liście pozwala dowiedzieć się, że trzeba go poprawić. Znaczenie origin i pustego file opisano w sekcji Jak adresowana jest encja. Żaden dokument za dowiązaniem prowadzącym poza katalog główny obszaru roboczego nie jest odczytywany: katalog poza katalogiem głównym nie jest przeszukiwany, a plik poza nim nie jest odczytywany niezależnie od tego, co deklaruje, więc encja, którą edytor pokazuje pod takim dowiązaniem, nie jest wymieniana jako należąca do obszaru roboczego — ani oferowana przez aggrega/attachCandidates czy aggrega/connectionCandidates, które odczytują te same dokumenty, nawet gdy dokument jest otwarty w edytorze. Obowiązuje to niezależnie od tego, co dokument deklaruje. Jedynym wyjątkiem jest encja Release wskazana w konfiguracji obszaru roboczego — jako build.authoring_release lub jako klucz workspace.releases, oceniana według pliku, do którego prowadzi dowiązanie, więc wskazanie dowiązania lub tego pliku liczy się tak samo — która jest odczytywana z pliku, do którego prowadzi dowiązanie, wymieniana w miejscu samego dowiązania, tak jak wymienia ją aggrega/releaseCandidates, i nie jest wskazywana jako nieodczytane dowiązanie; plik wskazany w jednym z tych ustawień, który deklaruje cokolwiek innego niż Release, nie jest wymieniany, a jego dowiązanie jest wskazywane. Skonfigurowane katalogi katalogu encji są sposobem, w jaki obszar roboczy odczytuje inne encje przechowywane gdzie indziej, więc dowiązanie do katalogu wymienionego w konfiguracji w catalog_dirs — dla obszaru roboczego lub dla encji Release — nie jest przeszukiwane tak jak własne dokumenty obszaru roboczego i również nie jest wskazywane: konfiguracja do niego sięgnęła, a jego Features są wymieniane z katalogu encji, tak jak w przypadku każdego skonfigurowanego katalogu. Features wymieniane z katalogów katalogu encji nigdy nie obejmują takiej, która znajduje się za dowiązaniem prowadzącym poza katalog, w którym muszą pozostać odczyty danego katalogu katalogu encji — obszar roboczy w przypadku katalogu wewnątrz niego lub sam katalog w przypadku katalogu wskazanego w konfiguracji poza nim — więc encja, którą odpowiedź wskazuje jako znajdującą się za nieodczytanym dowiązaniem, nigdy nie jest dodatkowo wymieniana obok tej nazwy. Odpowiedź wskazuje każde takie dowiązanie w unreadLinkedDirs w przypadku dowiązania do katalogu oraz w unreadLinkedFiles w przypadku dowiązania, którego własna nazwa kończy się na .yaml lub .yml i które prowadzi do pliku — względem katalogu głównego, w miejscu, gdzie znajduje się dowiązanie, w kolejności przeszukiwania obszaru roboczego — aby klient mógł wyjaśnić przyczynę. Dowiązanie pominięte przez wyszukiwanie ze względu na nazwę, położenie lub plik .gitignore nie jest wskazywane, a w odpowiedzi w kategoriach encji Release nie jest też wskazywane dowiązanie w katalogu katalogu encji odczytywanym wyłącznie przez inne Releases. Dowiązanie wewnątrz katalogu katalogu encji poza obszarem roboczym nie ma położenia względem katalogu głównego, pod którym można by je wskazać, i nie jest wskazywane. Oba pola są zawsze obecne i puste, gdy takiego dowiązania nie ma. Jeśli własny plik konfiguracyjny obszaru roboczego lub należąca do CI nakładka obok niego sam jest dowiązaniem prowadzącym poza obszar roboczy, plik ten jest wskazywany w unreadLinkedFiles niezależnie od tego, jak traktuje go wyszukiwanie, a indeks jest własnym odczytem obszaru roboczego bez żadnej konfiguracji — żaden katalog katalogu encji nie jest dla niego odczytywany, a indeks w kategoriach encji Release jest odrzucany; zob. Katalog główny obszaru roboczego i aktywna encja Release.
  • aggrega/entityDefinition — to, do czego rozwiązuje się wskazana encja: jej kind, własne name i version, description i publishScope, jeśli je ma, file, w którym została zadeklarowana, authoredLength tekstu źródłowego, z którego pochodzi, oraz definition jako dokument YAML z już zastosowanym dziedziczeniem. file jest zgłaszany dla każdego rodzaju jako ścieżka, którą można otworzyć — względna wobec katalogu głównego obszaru roboczego dla dokumentu wewnątrz niego, bezwzględna dla dokumentu poza nim, zgodnie z sekcją Jak zapisywana jest zgłaszana ścieżka. Jest pusty w jednym przypadku: encja rozwiązana z rejestru nie ma na tej maszynie dokumentu źródłowego, który można by wskazać. authoredLength odpowiada na inne pytanie — ile tekstu źródłowego zachowało rozwiązanie — i tylko encja Aggregate jest zwracana z jakimkolwiek tekstem, dlatego oba pola należy odczytywać osobno, a nie jako parę. name to tożsamość encji, zapisana tak, jak jedna encja odwołuje się do innej, i może zawierać przyrostek wersji. Jest to jedyne żądanie w tym miejscu, które wychodzi od nazwy, a nie od pozycji kursora, więc należy go użyć, gdy wiadomo już, o którą encję chodzi. release jest opcjonalny i rozwiązuje nazwę w kategoriach danej encji Release — zob. Odpowiadanie w kategoriach jednej encji Release. Nazwa, która nie rozwiązuje się do niczego, jest odrzucana, a nie zwracana z pustym dokumentem; zob. Rozróżnianie dwóch odmów dotyczących nazwy. name może zamiast tego być odwołaniem do rejestru — oci://<host>/<repository>:<tag> lub @<digest> w miejsce :<tag> — a odpowiedzią jest wtedy encja opublikowana pod tą współrzędną, odczytana z jej rejestru, przy czym published wskazuje, co zostało odczytane; zob. Pytanie o współrzędną.
  • aggrega/releaseClosure — domknięcie zależności encji Release: do których encji sięga i w jakich rozwiązanych wersjach, w entities, libraries i plugins, obok tożsamości aggregate i manifest, do których rozwiązały się jej dwa wskaźniki, wszelkich mappingDiagnostics zgłoszonych podczas rozwiązywania oraz deprecations zarejestrowanych dla tego, do czego sięga — w jej pliku blokady i w rejestrze zaufania wtyczek obok niego, dzięki czemu wycofana wtyczka dołączona w roli werdyktu jest wymieniana tak samo jak wycofane przypięte odwołanie. release to ścieżka względna wobec katalogu głównego obszaru roboczego wskazująca encję Release wewnątrz niego, ta sama wartość, którą przyjmuje aggrega/irGraph, odrzucana w tych samych przypadkach, i z tego samego powodu wymaga pliku blokady. Nic nie jest renderowane. Jej wpisy nie wskazują source: mówią, od czego zależy encja Release, a nie co zrobiło jedno uruchomienie — to zgłasza aggrega/resolveDependencies. Zob. Domknięcie nie jest grafem, ponieważ klient, który już otrzymuje graf, nie ma tych informacji.
  • aggrega/attachCandidates — które encje Features mogą zostać dołączone do węzła: te, których zadeklarowaną stosowalność spełniają etykiety węzła. Należy przesłać dokładnie jedną współrzędną. node wskazuje dokument przestrzeni roboczej po jego metadata.name; graphNode wskazuje węzeł na skompilowanym grafie release, po identyfikatorze, pod którym ten graf go przechowuje; labels przekazuje zbiór etykiet wprost i niczego nie wskazuje — dla klienta, który już go posiada. Odpowiedź powtarza współrzędną, dla której udzielono odpowiedzi — pustą, gdy nie było czego powtórzyć — zawiera nodeLabels, czyli pary etykiet, względem których oceniono dopasowanie, labelSource informujące, jakiego rodzaju jest to zbiór etykiet, oraz każdego kandydata jako kind, name, plik źródłowy i origin, które go adresują. Zwrócenie etykiet sprawia, że odpowiedź można zweryfikować na jej własnej podstawie: klient może wyjaśnić, dlaczego zaproponowano encję Feature, bez wyrabiania sobie własnego wyobrażenia o etykietach węzła — a właśnie w ten sposób odpowiedź klienta i odpowiedź kompilatora zaczynają się rozchodzić. Dla węzła grafu proponowane są te encje Features, do których dociera encja Release tego węzła. Obok graphNode parametr connection wskazuje jedno połączenie rysowane przez komponent tego węzła — jego socket i alias — a odpowiedź zawiera wtedy także slots, czyli każdy slot deklarowany przez gniazdo tego połączenia wraz z encjami Features, które mogą go wypełnić, albo noSlotReason, gdy żadnego nie można wypełnić. Zob. Co mówi odpowiedź z kandydatami do dołączenia.
  • aggrega/connectionCandidates — z czym może się połączyć wskazana encja. node to metadata.name encji, ta sama współrzędna, którą aggrega/attachCandidates przyjmuje pod tą nazwą. Zob. Co mówi odpowiedź z kandydatami do połączenia poniżej, ponieważ obie części odpowiedzi nie są jednakowo kompletne, a odpowiedź wskazuje, która jest która.
  • aggrega/insertionPoint — w którym miejscu dokumentu autorskiego należy umieścić nowy wpis pod wskazanym kontenerem, wyrażone tak, aby klient mógł go zastosować bez samodzielnego parsowania dokumentu. file wskazuje dokument należący do przestrzeni roboczej — względem katalogu głównego przestrzeni roboczej, bezwzględnie lub jako adres file://; dokument spoza katalogu głównego, czy to wprost, czy przez dowiązanie prowadzące poza niego — do pliku lub do katalogu po drodze — zostaje odrzucony niezależnie od zapisu, który go wskazuje, i niezależnie od tego, czy klient ma jego kopię; container to ścieżka strukturalna od korzenia dokumentu do kontenera, w którym ma się znaleźć wpis, a każdy jej element to klucz mapy lub pozycja w sekwencji zapisana dziesiętnie. Tę ścieżkę podaje klient — demon odczytuje własną strukturę dokumentu i nigdy nie ustala, gdzie coś należy umieścić, na podstawie jego nazwy. Zob. Co mówi odpowiedź z punktem wstawienia, ponieważ sama pozycja nie wystarcza do zastosowania edycji.
  • aggrega/attachmentContainer — w którym dokumencie należy umieścić dołączenie encji Feature dla węzła i w którym kontenerze wewnątrz niego. graphNode wskazuje węzeł na skompilowanym grafie release, po identyfikatorze, pod którym ten graf go przechowuje, i oba parametry są wymagane: identyfikator węzła jest kluczem grafu jednej encji Release i bez niej nic nie znaczy. Odpowiedź zawiera node, file i container — listę segmentów dokładnie w postaci, którą przyjmuje aggrega/insertionPoint, dzięki czemu obie metody łączą się bez konieczności ustalania czegokolwiek pomiędzy nimi. Dla dołączenia do jednego połączenia rysowanego przez komponent węzła należy dodać connection z jego socket, alias i document — aggregate lub release — a odpowiedź wskaże wtedy własny kontener features tego połączenia w tym dokumencie. Zob. Co mówi odpowiedź z kontenerem dołączenia, ponieważ file jest częścią odpowiedzi, a nie czymś, co klient już zna.
  • aggrega/connectionAtPosition — w obrębie wpisu którego połączenia znajduje się pozycja w encji Aggregate lub Release, wyrażone w kategoriach, w jakich dwie powyższe metody przyjmują połączenie. file wskazuje dokument tak, jak wskazuje go aggrega/insertionPoint, i jest odczytywany najpierw z tego, co sesja dla niego przechowuje; position to miejsce w nim, line i character liczone od zera w kodowaniu sesji; release wskazuje encję Release, której skompilowany graf rejestruje połączenia, i jest wymagany także dla pozycji w encji Aggregate, ponieważ węzeł grafu i połączenie istnieją tylko na skompilowanym grafie. Odpowiedź zawiera graphNode i connection — jego socket, alias i document, w którym odczytano pozycję — do przekazania bez zmian do aggrega/attachCandidates i aggrega/attachmentContainer, albo noConnectionReason, gdy w tym miejscu nie zapisano żadnego połączenia. Zob. Co mówi odpowiedź z połączeniem w pozycji.
  • aggrega/editDocument — stosuje jedną ograniczoną edycję strukturalną do dokumentu autorskiego, zachowując każdy bajt, którego nie dotyka. Stanowi drugą połowę dwóch powyższych metod lokalizujących: tamte wskazują, gdzie należy umieścić wpis, i pozostawiają jego złożenie i zastosowanie klientowi, ta składa i stosuje jeden wpis. edit wskazuje jedną z czterech operacji — add-component, attach-feature, wire-edge, set-value — a wartość spoza nich zostaje odrzucona, a nie zinterpretowana; node to ścieżka strukturalna od korzenia dokumentu, lista segmentów dokładnie w postaci, którą przyjmuje aggrega/insertionPoint; name to klucz, pod którym zapisywany jest wpis, a value to jego zawartość, której znaczenie wynika z edit; socket jest odczytywany dla wire-edge i ignorowany w pozostałych przypadkach. dryRun wykonuje wszystko, co zwykłe żądanie, z wyjątkiem zapisu, i zwraca edytowany dokument jako content — dla klienta, który najpierw przedstawia wynik autorowi; w tym trybie nic nie jest tworzone, a written jest puste. file wskazuje dokument względem katalogu głównego przestrzeni roboczej lub ścieżką bezwzględną, a dokument spoza katalogu głównego — wprost lub przez dowiązanie prowadzące poza niego, do pliku lub do katalogu po drodze — zostaje odrzucony bez odczytu i zapisu czegokolwiek. Ta metoda zapisuje wskazany dokument wewnątrz przestrzeni roboczej — nie rozwiązuje żadnej zależności, nie łączy się z żadnym rejestrem i nie korzysta z sieci w żadnym trybie dostarczania, a zapis jest uzależniony od pomyślnej walidacji złożonego dokumentu względem schematu jego rodzaju. Zob. Co mówi odpowiedź z edycji dokumentu, ponieważ domyślnie następuje zapis, a odmowa pozostawia plik bajt w bajt w niezmienionym stanie.
  • aggrega/releaseCandidates — dokumenty Release obszaru roboczego wskazanego w żądaniu, jako ścieżki bezwzględne. Przyjmuje obszar roboczy i nic więcej: zbiór jest właściwością katalogu głównego tego obszaru roboczego. O przynależności decyduje rodzaj dokumentu — kind: pliku to Release — a nie nazwa pliku, więc encja Release nazwana bez konwencjonalnego prefiksu jest oferowana, a plik jedynie nazwany jak taka encja — nie. To właśnie ten zbiór powinien wyświetlać selektor „który Release?” w edytorze, ponieważ jest to ten sam zbiór, z którego wybiera opisana niżej kaskada aktywnej encji Release. Odpowiedź zawiera też lockfiles, które przypisuje każdej wymienionej encji Release — kluczem jest dokładnie ten ciąg, pod którym wymienia ją releases — ścieżkę bezwzględną jej pliku blokady; pole to jest zawsze obecne i jest pustym obiektem, gdy obszar roboczy nie zawiera żadnej encji Release. Zawiera także unreadLinkedDirs, wskazujące — względem katalogu głównego, tam gdzie znajduje się dowiązanie — każde dowiązanie, które stoi w miejscu, gdzie listowanie odczytałoby katalog, i prowadzi do katalogu poza katalogiem głównym obszaru roboczego: żaden katalog poza katalogiem głównym nie jest przeszukiwany, więc encja Release, którą edytor pokazuje w takim katalogu, nie jest wymieniana, a to pole pozwala selektorowi wyjaśnić dlaczego. Dowiązanie do katalogu, który konfiguracja obszaru roboczego wymienia w catalog_dirs, nie jest wskazywane: konfiguracja do niego sięgnęła, jako do katalogu katalogów, a nie miejsca przechowywania encji Releases. Pole jest zawsze obecne i puste, gdy takiego dowiązania nie ma. Obok niego unreadLinkedFiles wskazuje w ten sam sposób każde dowiązanie, którego własna nazwa kończy się na .yaml lub .yml i które prowadzi do pliku poza katalogiem głównym obszaru roboczego: żaden taki plik nie jest odczytywany, bez względu na zawartość, więc encja Release osiągalna tylko przez jedno z tych dowiązań nie jest wymieniana, a krok kaskady opisanej niżej dotyczący pojedynczej encji Release jej nie uwzględnia. Wyjątkiem jest plik, który konfiguracja obszaru roboczego wskazuje jako Release — jako build.authoring_release lub jako klucz workspace.releases, oceniany według pliku, do którego prowadzi dowiązanie, więc wskazanie dowiązania i wskazanie tego pliku liczą się jednakowo — który jest odczytywany i wymieniany w miejscu samego dowiązania, a nie wskazywany, pod warunkiem że deklaruje Release; plik deklarujący cokolwiek innego nie jest wymieniany, a jego dowiązanie jest wskazywane. Pole jest zawsze obecne i puste, gdy takiego dowiązania nie ma. Jeśli własny plik konfiguracyjny obszaru roboczego lub należąca do CI nakładka obok niego sam jest dowiązaniem prowadzącym poza obszar roboczy, plik ten jest tu wskazywany niezależnie od tego, jak traktuje go wyszukiwanie, a listowanie jest odczytywane bez żadnej konfiguracji, więc encja Release, którą konfiguracja wskazałaby przez dowiązanie, nie jest wymieniana; zob. Katalog główny obszaru roboczego i aktywna encja Release. Zob. Gdzie znajduje się plik blokady encji Release.
  • aggrega/activeRelease — na którą encję Release wskazuje obszar roboczy wskazany w żądaniu, jako ścieżka bezwzględna w polu release, dla klienta decydującego, co wybrać domyślnie. Przyjmuje obszar roboczy i nic więcej. Pole jest zawsze obecne, a pusta wartość oznacza, że obszar roboczy nie wskazuje żadnej — jest to odpowiedź pomyślna, a nie błąd, więc klient odświeżający ją przy każdym restarcie demona nie musi traktować zwykłego obszaru roboczego jako awarii. Gdy wartość jest pusta, odpowiedź zawiera też reason, jednowierszowe podsumowanie tego, czego szukała kaskada, oraz trace, opis jej przebiegu krok po kroku; oba są pomijane, gdy encja Release została rozstrzygnięta. Gdy encja Release została rozstrzygnięta, odpowiedź zawiera zamiast nich lockfile, ścieżkę bezwzględną pliku blokady tej encji Release, pomijaną, gdy żadna nie została rozstrzygnięta. Wskazana encja Release nie musi należeć do tych, które wymienia aggrega/releaseCandidates — znacznik może wskazywać encję Release w katalogu pomijanym przez to listowanie, takim jak vendor/, albo nazwaną bez rozszerzenia YAML — dlatego to z tej odpowiedzi klient odczytuje plik blokady domyślnej encji Release. Zob. Gdzie znajduje się plik blokady encji Release. Należy o nią pytać, zamiast wyprowadzać odpowiedź z jednego z wejść kaskady: wejście, z którego kaskada ostatecznie nie skorzystała, wskazuje inną encję Release niż ta, którą wybrała. Odpowiedź jest obliczana w chwili zapytania, więc ponowne zapytanie po zapisaniu znacznika, edycji konfiguracji lub dodaniu pliku Release zwraca nową odpowiedź, a nie stan obszaru roboczego z chwili uruchomienia demona.
  • aggrega/setActiveRelease — zapisuje encję Release jako domyślną dla obszaru roboczego wskazanego w żądaniu, zapisując znacznik .aggrega/active-release tego obszaru roboczego, i odpowiada dokładnie tak, jak aggrega/activeRelease odpowiada po zapisaniu znacznika. Przyjmuje obszar roboczy i release: ścieżkę względną wobec katalogu głównego obszaru roboczego, wskazującą encję Release wewnątrz niego, podlegającą tej samej umowie co release w aggrega/irGraph — ścieżka bezwzględna, ścieżka wychodząca poza obszar roboczy i pusta wartość są odrzucane, podobnie jak ścieżka prowadząca na zewnątrz przez dowiązanie, chyba że konfiguracja obszaru roboczego wskazuje tę encję Release. Znacznik to jeden wiersz wskazujący encję Release względem katalogu głównego, w postaci odczytywanej przez opisaną niżej kaskadę. Jest zapisywany wewnątrz obszaru roboczego i nigdzie indziej: jeśli .aggrega lub sam znacznik jest dowiązaniem prowadzącym poza obszar roboczy — niezależnie od tego, czy miejsce docelowe już istnieje — żądanie jest odrzucane błędem invalid-params, którego komunikatem jest zdanie danego warunku poprzedzone jego krótkim kodem, E0320: … (fatal-halts.md §„A path the operation writes leads through a link out of the directory it must stay inside (Ścieżka zapisywana przez operację prowadzi przez dowiązanie poza katalog, w którym musi pozostać)”), wskazującym dowiązanie i miejsce, do którego prowadzi, i nic nie jest zapisywane; przez dowiązanie pozostające wewnątrz obszaru roboczego zapis jest wykonywany. Odpowiedź podaje to, na czym ustala się kaskada, a nie powtarza wysłanej wartości, i obie różnią się, gdy build.authoring_release wskazuje encję Release, ponieważ konfiguracja ma pierwszeństwo przed znacznikiem. Wartość domyślną należy zapisywać w ten sposób, a nie samodzielnie zapisując plik, aby o miejscu zapisu znacznika decydowała reguła, której podlega każdy plik zapisywany przez produkt w obszarze roboczym — zob. Granica obszaru roboczego.
  • aggrega/effectiveConfiguration — konfiguracja obowiązująca dla obszaru roboczego wskazanego w żądaniu oraz warstwa, z której pochodzi każde ustawienie. Przyjmuje obszar roboczy i nic więcej: odpowiedź jest właściwością tego obszaru roboczego. layers wymienia pliki konfiguracyjne i nadpisania ze zmiennych środowiskowych, które miały wkład, od najniższego pierwszeństwa; settings zawiera każde przypisane ustawienie jako jego nazwę z kropkami, wartość efektywną i source, które ją określiło. source jest zapisywane dokładnie tak jak odpowiadający mu wpis w layers, więc oba można bezpośrednio połączyć. Zob. Co obejmuje odpowiedź z efektywną konfiguracją, aby dowiedzieć się, którą warstwę wskazuje source i jakie są granice znaczenia wiersza.
  • aggrega/configInit — tworzy działającą konfigurację przez zarejestrowanie rejestru i jego polityki zaufania do podpisów, tak aby nowa maszyna mogła pobierać i weryfikować podpisane artefakty bez ręcznej edycji YAML. registry jest opcjonalne, a brak wartości powoduje zarejestrowanie oficjalnego huba, tej samej wartości domyślnej, którą ma aggrega config init; host w odpowiedzi wskazuje, który z nich został użyty. global i workspace to nadpisania celu zapisu, a wysłanie obu jest odrzucane. Żądanie odmawia zamiast nadpisać istniejący plik konfiguracyjny, wskazując ten plik — należy wysłać force, aby mimo to kontynuować, co scala wpis rejestru z istniejącą zawartością i zachowuje pozostałe ustawienia. dryRun wykonuje wszystko to, co zwykłe żądanie, z wyjątkiem zapisu, i odpowiada utworzoną konfiguracją jako content, dla klienta, który przedstawia dokument autorowi przed zapisaniem; w tym trybie nic nie jest tworzone, a written ma wartość false. Odmowa z powodu istniejącego pliku obowiązuje także przy dryRun, więc należy wysłać razem z nim force, aby otrzymać scalenie, jakie dałby zapis nadpisujący. W obszarze roboczym offline można zarejestrować tylko oficjalny hub: to żądanie nie przyjmuje tożsamości ani klucza, więc każdy inny rejestr jest odrzucany dokładnie tak, jak odrzuca go aggrega/registryAdd, łącznie z krótkim kodem i zdaniem, i należy go dodać tamtym żądaniem z ręcznie podaną polityką. Odpowiedź zawiera host, scope, trust i written oraz existed, mające wartość true, gdy plik konfiguracyjny już istniał — więc wpis rejestru jest z nim scalany zamiast tworzenia nowego pliku — i nieobecne, gdy plik jest tworzony. Domyślnie zapisywana jest konfiguracja globalna — zob. Dostęp do rejestru i zapis.
  • aggrega/configCapture — zamraża efektywną konfigurację krytyczną dla budowania we własnym pliku konfiguracyjnym tego obszaru roboczego, tak aby obszar roboczy budował się tak samo bez globalnej konfiguracji maszyny pod spodem. Nie przyjmuje celu zapisu: zamrażanie służy temu, by jeden obszar roboczy był samowystarczalny, więc zawsze zapisuje plik tego obszaru roboczego. allPlugins rozszerza zamrażany zbiór z gniazd określających renderowany wynik — powiązań providerów i dołączeń governance typu label-transform — na wszystkie gniazda pluginów, dodając bramki governance werdyktów i linterów oraz gniazdo importu. Odpowiedź zawiera configFile, workspaceRoot, captured, sockets i catalogDirs. Zob. Co pozostawia po sobie zapis konfiguracji, ponieważ odpowiedź wskazuje dokument, który teraz istnieje, a kolejnym krokiem klienta jest jego otwarcie.
  • aggrega/skillsInstall — zapisuje wbudowaną w ten plik binarny umiejętność Aggrega do folderu umiejętności każdego asystenta wskazanego w żądaniu; to ta sama instalacja, którą aggrega skills install wykonuje w terminalu. agents wymienia asystentów według identyfikatorów — tych, które zgłasza aggrega/skillsList; identyfikator podany dwukrotnie jest instalowany raz, a gdy kilku wskazanych asystentów czyta jeden wspólny folder, umiejętność jest tam zapisywana raz. Instalacja w projekcie wymaga tego pola. Żądanie global, które nie wskazuje żadnego asystenta, instaluje umiejętność dla asystentów znalezionych na tej maszynie, tak jak aggrega skills install --global bez --agent — dla każdego, którego folder konfiguracyjny znajduje się w katalogu domowym lub którego polecenie jest w PATH środowiska demona — a gdy żadnego nie znaleziono, jest odrzucane bez zapisania czegokolwiek; nie pojawia się żaden monit, a installed wskazuje asystentów, dla których zapisano umiejętność. Bez global umiejętność trafia do folderu projektu każdego asystenta w obszarze roboczym wskazanym w żądaniu, nigdy do katalogu, w którym uruchomiono demona; z global: true trafia do folderu użytkownika każdego asystenta w katalogu domowym wskazanym przez środowisko demona (HOME lub USERPROFILE w systemie Windows). Każde miejsce docelowe jest sprawdzane, zanim cokolwiek zostanie zapisane, więc odmowa pozostawia każdy folder bez zmian: identyfikator, dla którego nie jest znany żaden folder umiejętności, jest odrzucany ze wskazaniem go i listą istniejących identyfikatorów, a plik w miejscu docelowym, który nie zawiera wiersza komentarza obecnego w każdej zapisanej kopii umiejętności, jest odrzucany ze wskazaniem jego ścieżki. Kopia zawierająca ten wiersz — zapisana przez wcześniejszą instalację lub pobrana z opublikowanego repozytorium umiejętności — jest zastępowana; w ten sposób nowsza wersja aggrega aktualizuje umiejętność do własnej wersji. Folder projektu osiągany przez dowiązanie prowadzące poza obszar roboczy jest odrzucany bez zapisania czegokolwiek, tak jak każdy zapis demona w obszarze roboczym — zob. Granica obszaru roboczego. Odpowiedź zawiera skill, installed — jeden wpis na każdy zapisany folder, w kolejności wskazania asystentów, każdy z agents, którzy go czytają, bezwzględną ścieżką folder i replaced — oraz scope. Z global zapisuje to foldery czytane przez każdy projekt na maszynie — zob. Łączenie z rejestrem i zapis.
  • aggrega/skillsList — umiejętności dostarczane z tym plikiem binarnym i każdy asystent, dla którego aggrega/skillsInstall może je zapisać; to lista, którą wypisuje aggrega skills list. Przyjmuje tylko obszar roboczy i niczego z niego nie odczytuje. skills zawiera name i description każdej umiejętności; agents zawiera dla każdego asystenta id, name, projectFolder — względny wobec katalogu głównego projektu, którym na tej powierzchni jest obszar roboczy wskazany w żądaniu — oraz userFolder, względny wobec katalogu domowego; obie ścieżki są rozdzielane ukośnikami, a wpisy uporządkowane według identyfikatora. Niczego nie zapisuje i z niczym się nie łączy.
  • aggrega/pluginAdd — przeszukuje skonfigurowany rejestr w poszukiwaniu pluginu wskazanego typu i dodaje go do konfiguracji. type i query są wymagane: type to jedna z wartości provider, governance, linter, importer i cli, a query jest dopasowywane do nazw pluginów tego typu i musi wskazywać dokładnie jeden, więc zapytanie pasujące do kilku jest odrzucane wraz z kandydatami, a nie rozstrzygane arbitralnie. capability wskazuje możliwość obsługiwaną przez powiązanie provider i jest tam wymagane; role wskazuje rolę dołączenia governance — label-transform, ir-verdict lub render-verdict — i jest tam wymagane; każde z nich jest odczytywane tylko dla własnego typu i odrzucane przy każdym innym, ponieważ pole, które po cichu nic nie robi, sprawiałoby wrażenie, że zadziałało. acceptCapabilities jest wymagane dla cli i potwierdza zadeklarowane możliwości tego pluginu: polecenie terminalowe uzyskuje tę decyzję, pytając, a ten interfejs nie ma kogo zapytać, więc wywołujący uzyskuje ją i przesyła. global i workspace to nadpisania celu zapisu, a wysłanie obu jest odrzucane. dryRun wykonuje wszystko to, co zwykłe żądanie, z wyjątkiem zapisu, i odpowiada wynikową konfiguracją jako content; nic nie jest tworzone ani modyfikowane, a written ma wartość false. Rejestr jest mimo to przeszukiwany, a wersja rozstrzygana, ponieważ tożsamość w tej zawartości to tożsamość, którą przypiąłby zapis. dryRun jest odrzucane dla typu cli, a nie ignorowane: dodanie rozszerzenia poleceń zapisuje skrót zawartości zweryfikowanych bajtów, czyli zapis utrzymywany przez kompilator, a nie treść edytowaną przez kogokolwiek, a dodanie na bieżąco umieszcza te bajty w pamięci podręcznej — dlatego jest zapisywane, a nie zwracane. Wersja jest przypinana automatycznie — zapytanie wskazuje jeden plugin, a we wpisie zapisywana jest wersja, którą zapytanie wskazuje jako <name>:<version>, albo w przeciwnym razie najwyższa opublikowana wersja pluginu; wskazana wersja wycofana przez deklarację wycofania, której ufa ten obszar roboczy, jest przypinana mimo to, a odpowiedź zawiera withdrawn: true. To żądanie łączy się z rejestrem, a dodanie typu cli bez wskazania zakresu zapisuje konfigurację globalną — zob. Dostęp do rejestru i zapis. Zob. Co mówi zmiana pluginu.
  • aggrega/pluginRemove — usuwa wpis skonfigurowanego pluginu, tak aby przestał uczestniczyć. type przyjmuje ten sam zbiór co dodanie, a query identyfikuje wpis: krótką nazwę pluginu, jego przypiętą referencję lub — dla provider — możliwość obsługiwaną przez powiązanie. Oba są wymagane. global i workspace to te same nadpisania celu zapisu, odrzucane razem w ten sam sposób. Zapytanie niepasujące do żadnego wpisu jest odrzucane, a nie zwracane jako sukces przy niezmienionej konfiguracji, więc wywołujący nigdy nie dowie się, że plugin przestał uczestniczyć, gdy tak się nie stało, a literówka nigdy nie usunie innego pluginu. Żądanie nie łączy się z żadnym rejestrem: usuwanie działa wyłącznie na tekście konfiguracji. Usunięcie typu cli bez wskazania zakresu zapisuje konfigurację globalną — zob. Dostęp do rejestru i zapis. Zob. Co mówi zmiana pluginu.
  • aggrega/pluginSync — uzgadnia zapisy encji Plugin utrzymywane przez maszynę z jej modułem: zbiór funkcji hosta wyprowadzony z własnych importów modułu oraz odzwierciedlenie poleceń odczytane z autoraportu modułu. Żaden z tych zapisów nie jest tworzony ręcznie, ponieważ oba mają swoje źródło prawdy w module. Oba pola są wymagane i żadne nie ma wartości domyślnej — zapisy są wyprowadzane z modułu, więc uzgodnienie bez wskazania żadnego nie ma do czego się odnieść — i oba są ścieżkami względnymi wobec katalogu głównego obszaru roboczego, odrzucanymi, gdy są bezwzględne lub prowadzą poza niego, wprost lub przez dowiązanie. Zmieniają się tylko te dwa bloki: każdy inny bajt pozostaje bez zmian, łącznie z komentarzami, pustymi wierszami i stylem cudzysłowów, a plik, który już zapisuje to, co wynika z modułu, pozostaje identyczny co do bajtu i jest zgłaszany jako niezmieniony. Zapisywany jest wskazany plik encji, wewnątrz obszaru roboczego, a żądanie nie łączy się z żadnym rejestrem. Zob. Co mówi zmiana pluginu.
  • aggrega/pluginGenCatalog — generuje jedną encję Plugin na każdego wybranego gościa, scalając pola kontraktu wyprowadzone z samoopisu gościa z napisaną przez autora nakładką dla danego pluginu. fromEmbedded i plugin to dwa tryby wyboru i obowiązuje dokładnie jeden: każdy gość, którego zawiera ten plik binarny, albo jeden moduł pod wskazaną ścieżką; podanie obu lub żadnego jest odrzucane, a nie rozstrzygane. overlay jest wymagane i jest katalogiem nakładek w trybie fromEmbedded albo pojedynczym plikiem nakładki w trybie plugin — gdy gości jest kilku, nakładka jest dopasowywana do gościa po tożsamości, a gdy jest jeden, nie ma czego dopasowywać. outputDir jest wymagane w obu sposobach dostarczenia i dryRun go nie zwalnia: przebieg próbny zmienia to, dokąd trafia treść, a nie to, dla którego pliku jest to treść, więc każdy zwrócony dokument nadal wskazuje ścieżkę, dla której jest przeznaczony, a ta ścieżka jest składana z tego katalogu. Trzy podane tu ścieżki nie są oceniane jednakowo, a podział wynika z tego, co generowanie robi z każdą z nich. plugin i overlay są odczytywane i obie są plikami wybranymi przez użytkownika — moduł trafia do katalogu, do którego buduje jego zestaw narzędzi, a jego nakładka jest pisana obok niego — więc każda może być ścieżką bezwzględną i jest odczytywana tam, gdzie faktycznie się znajduje. Do outputDir następuje zapis, więc jest to ścieżka względna wobec katalogu głównego obszaru roboczego, odrzucana, gdy jest bezwzględna lub wskazuje poza niego, wprost albo przez dowiązanie — jeszcze nieutworzony katalog pod dowiązanym katalogiem prowadzącym na zewnątrz jest odrzucany tak jak tamten katalog. Ponowne uruchomienie na niezmienionych danych wejściowych daje bajtowo identyczne encje. Zapisuje to wygenerowane encje w outputDir, wewnątrz obszaru roboczego, chyba że dryRun żąda ich zamiast tego jako treści. Zob. Co mówi zmiana pluginu.
  • aggrega/getSchema — JSON Schema dla rodzaju encji lub kontraktu, odczytany z kopii wkompilowanej w uruchomiony plik binarny. kind to token schematu zapisany małymi literami z łącznikami — component, aggregate, release, recipe, ir, wasm-provider itd. — i jest opcjonalny, ponieważ wybiera, na które z dwóch pytań oczekuje się odpowiedzi. Gdy podany jest rodzaj, odpowiedź zawiera kind i schema, czyli schemat jako dokument JSON, a nie jako ciąg znaków go zawierający. Gdy żaden nie jest podany, odpowiedź zawiera zamiast tego kinds i entityKinds: rodzaje, które można podać, w dwóch zakresach. kinds to każdy token, o który można zapytać ten plik binarny, w tej samej kolejności, w jakiej wypisuje je aggrega get-schema --list. entityKinds to węższy zbiór rodzajów, w których autor pisze dokumenty; każdy wpis zawiera token kind do odesłania, wartość documentKind, która trafia do własnego pola kind: dokumentu, oraz acceptedBy, informujące, czy walidacja pojedynczej encji, publikacja i inspekcja po nazwie przyjmują dokument tego rodzaju. Przed zbudowaniem selektora na podstawie któregokolwiek z nich należy zapoznać się z sekcją Jakie rodzaje można zaproponować autorowi. Odpowiedź ze schematem i wyliczenie nigdy nie są łączone, więc z odpowiedzi można odczytać, na które pytanie udzielono odpowiedzi. Token, któremu nie odpowiada żaden schemat, jest odrzucany z pełnym zbiorem poprawnych wartości w komunikacie, dzięki czemu literówkę można poprawić bez drugiego wywołania. Żądanie nie pobiera niczego z obszaru roboczego, nie kontaktuje się z żadnym rejestrem i niczego nie zapisuje, więc odpowiada nawet w zupełnie pustym obszarze roboczym — co pozwala używać go do powiązania schematów edytora z plikiem binarnym, który edytor faktycznie uruchamia, a nie z kopią schematów zainstalowaną gdzie indziej.
  • aggrega/scaffoldEntity — dokument startowy dla rodzaju encji: dokładnie te pola, których wymaga schemat tego rodzaju, z wypełnionymi stałymi apiVersion i kind oraz symbolem zastępczym wszędzie tam, gdzie potrzebna jest wartość. kind jest wymagany i jest tokenem schematu zapisanym małymi literami z łącznikami — component, aggregate, release, recipe, manifest, feature itd.; aggrega/getSchema bez kind informuje, które tokeny można wysłać, a token, któremu nie odpowiada żaden schemat, jest odrzucany z tym zbiorem w komunikacie, dzięki czemu literówkę można poprawić bez drugiego wywołania. Klient proponujący autorowi wybór rodzaju odczytuje entityKinds tej metody, czyli zbiór rodzajów, w których można napisać dokument. name jest opcjonalne i wypełnia metadata.name dla rodzajów, których schemat tego wymaga. Odpowiedź zawiera kind i skeleton. Zob. Co daje odpowiedź ze szkieletem, ponieważ odpowiedź jest dokumentem do zapisania, a nie dokumentem, który został zapisany. Szkielet jest wyprowadzany z tego samego schematu, który zwraca aggrega/getSchema, więc obie odpowiedzi pochodzą z jednego źródła. Gdy zamiast kind zostanie wysłane example, metoda zapisuje jeden z przykładów gotowych do uruchomienia z dokumentacji do nowego katalogu obszaru roboczego, tak jak robi to w terminalu aggrega scaffold --example; gdy zostanie wysłane samo list: true, odpowiada wszystkimi dostępnymi przykładami i niczego nie zapisuje. Obie formy wymagają obszaru roboczego, więc żądanie dowolnej z nich wskazuje go w workspaceRoot, a żądanie, które go nie wskazuje, jest odrzucane. dir wskazuje nowy katalog względem katalogu głównego obszaru roboczego, a domyślnie jest nim nazwa przykładu; wartość bezwzględna lub taka, która rozwiązuje się poza katalog główny — w zapisanej postaci lub przez dowiązanie — jest odrzucana, zanim cokolwiek zostanie odczytane, a katalog, który cokolwiek zawiera, jest odrzucany i pozostawiany bez zmian. Odpowiedź na listę zawiera examples, każdy z name, level i summary; odpowiedź na zapis zawiera example, dir, files — każdy zapisany plik, względem dir — next, polecenia, które strona przykładu podaje do jego zbudowania, nieobecne, gdy ich nie podaje, oraz version, wersję dokumentacji, z której odczytano przykład. Pola dwóch form wysłane razem — kind z example, list z example lub kind, name z example lub list albo dir bez example — są odrzucane, zanim cokolwiek zostanie odczytane, tymi samymi słowami, którymi odrzuca je narzędzie asystenta. Zapis pozyskuje pakiet dokumentacji, jeśli maszyna nie ma kopii, którą dopuszcza własna weryfikacja podpisu obszaru roboczego, i zapisuje wewnątrz obszaru roboczego — zob. Dostęp do rejestru i zapis.
  • aggrega/import — przekształca obcy opis źródłowy w robocze pliki autorskie Aggrega; jest to ta sama konwersja, którą aggrega import wykonuje w terminalu. source jest wymagane i wskazuje plik lub katalog do konwersji, jako ścieżkę bezwzględną albo względną wobec katalogu głównego obszaru roboczego — opis wyeksportowany przez inne narzędzie znajduje się tam, gdzie go zapisano, więc jest odczytywany tam, gdzie faktycznie się znajduje, a nie tylko wewnątrz obszaru roboczego. Katalog jest odczytywany tak, jak odczytuje go aggrega import: ograniczony do tych jego plików, które wybierają zadeklarowane wzorce plików importera, z pominięciem folderu wyników kompilacji obszaru roboczego dist/, i zamknięty w sobie, gdziekolwiek się znajduje, więc żadne dowiązanie w nim nie jest śledzone poza niego. outputDir jest opcjonalne i wskazuje katalog, do którego trafiają wersje robocze, i nie podlega tej zasadzie: następuje do niego zapis, więc jest to ścieżka wewnątrz obszaru roboczego, a wartość bezwzględna lub wskazująca poza katalog główny — wprost albo przez dowiązanie, łącznie z jeszcze nieutworzonym katalogiem pod takim dowiązaniem — jest odrzucana. Gdy zostanie pominięte, wersje robocze trafiają pod katalog główny obszaru roboczego, tam, gdzie zapisuje je aggrega import, gdy nie wskazuje miejsca docelowego — również przy dryRun. format jawnie wskazuje format źródła; gdy zostanie pominięty, format jest rozpoznawany po sygnaturach deklarowanych przez importery — zarówno z katalogu obszaru roboczego, jak i importery rdzenia kompilatora — a źródło, którego żaden nie rozpoznaje albo które rozpoznają importery więcej niż jednego formatu, jest odrzucane z prośbą o format, zamiast zgadywania. target wskazuje możliwość dostawcy, taką jak compose lub helm — słowo, z którym wiąże się spec.capability encji Recipe — i obok wersji roboczych importera tworzy roboczy Manifest, względem którego buduje się roboczy Release dla tego dostawcy, dokładnie tak jak aggrega import --target: manifest.yaml, mapujący każdy typ komponentu i każdy typ funkcji potrzebny wersjom roboczym — łącznie z typami katalogowej encji Aggregate, którą roboczy Aggregate włącza w swój skład — na Recipe lub recepturę funkcji tej możliwości, jaką katalog obszaru roboczego dla niego oferuje, według nazwy kwalifikowanej możliwością, bez wersji: na jedyną, jaka istnieje, albo spośród kilku na tę nazwaną od typu. spec.manifest encji Release jest ustawiane na niego; typ bez żadnej albo z kilkoma, z których żadna nie ma takiej nazwy, pozostaje niezmapowany, z ustaleniem warn, które go wskazuje, a mapowanie utworzone przez sam importer jest zachowywane tam, gdzie katalog oferuje je dla tego typu i tej możliwości, a w przeciwnym razie odrzucane z ustaleniem warn. target, z którym nie wiąże się żaden Recipe w katalogu, jest odrzucany przed uruchomieniem importera, z podaniem go i możliwości, z którymi wiążą się Recipes katalogu, i nic nie jest zapisywane; gdy zostanie pominięty, Manifest nie jest tworzony — z wyjątkiem trybu sync, który tworzy go dla celu wskazanego w zapisie wcześniejszego importu. Importer rdzenia, którego maszyna jeszcze nie ma, jest pobierany przez pierwszy import, który go potrzebuje — zob. Co mówi odpowiedź importu. dryRun robi wszystko to, co zwykłe żądanie, z wyjątkiem zapisu, i zwraca wersje robocze jako treść, dla klienta, który najpierw pokazuje je autorowi; nic nie jest tworzone, a written jest puste. sync aktualizuje względem źródła to, co wcześniejszy import utworzył w outputDir, zmieniając tylko to, co zapisał import, tak jak aggrega import --sync; bez niego żądanie, którego wersje robocze nadpisałyby istniejący już Aggregate, jest odrzucane. Odpowiedź zawiera format, outputDir, written, files, drift, diagnostics, decisions i halted. Zob. Co mówi odpowiedź importu, ponieważ źródło, którego importer nie mógł w pełni przekonwertować, daje odpowiedź pomyślną, a nie błąd.
  • aggrega/explainError — to, co kompilator deklaruje o warunku wskazanym przez kod, oraz opublikowane wpisy objaśniające poprawkę w dokumentach. code jest wymagany i przyjmuje dowolny z identyfikatorów warunku: krótki kod, który diagnostyka niesie w shortCode, lub opisowy w code. Jest to rozwinięcie kodu, który diagnostyki przesyłane tym protokołem już niosą, i jest to ta sama odpowiedź, którą aggrega explain wypisuje w terminalu. Odpowiedź zawsze zawiera warunek — shortCode, code i message — ponieważ tyle jest zadeklarowane w pliku binarnym i nie wymaga sieci; entries zawiera opublikowane omówienie, a note wyjaśnia, dlaczego go brakuje, jeśli go brakuje. Pobiera to pakiet dokumentacji, jeśli maszyna nie ma kopii, którą dopuszcza własna weryfikacja podpisu obszaru roboczego — zob. Dostęp do rejestru i zapis. Zob. Rozwijanie kodu przesłanego w diagnostyce.
  • aggrega/invalidate — sygnał unieważnienia pamięci podręcznej z mechanizmu obserwowania plików edytora.

Powiadomienia:

  • $/cancelRequest — od klienta do serwera: zatrzymanie trwającego żądania wysłanego pod danym identyfikatorem. Demon anuluje pracę tego żądania; operacja zauważa anulowanie na najbliższej granicy kroku, a nie natychmiast, więc już rozpoczęta praca trwa jeszcze przez chwilę. Anulowanie identyfikatora, pod którym nic nie działa, jest bezpieczną operacją bez skutku.
  • $/progress — od serwera do klienta: co długa operacja robi w trakcie działania, z użyciem tokenu, na który żądanie poprosiło o raportowanie. Wysyłane tylko dla żądania, które taki token zawierało. Zob. Obserwowanie długiej operacji.
  • aggrega/shutdown — rozpoczęcie kooperacyjnego wygaszania: trwające żądania kończą się, nowe są odrzucane, po czym demon kończy działanie.
  • aggrega/publishDiagnostics — zestaw diagnostyk wysyłany przez serwer (używany dla ostrzeżeń o rozbieżności pliku blokady i stanu przy uruchomieniu). Każdy wpis zawiera pole source wskazujące, która z warstw diagnostycznych demona go zgłosiła: aggrega dla ustalenia dotyczącego napisanych dokumentów, aggrega-build dla ostrzeżenia zgłoszonego przez kompilację — każdego zgłoszonego przez nią ostrzeżenia, czyli tego samego zestawu, który wypisuje aggrega build — oraz aggrega-lint dla ustalenia dotyczącego konwencji publikowania, tych samych ustaleń, które wypisuje aggrega lint. Pole jest zawsze obecne w każdym wpisie, więc klient może je grupować zamiast pokazywać jedną niezróżnicowaną listę i nigdy nie musi odróżniać braku źródła od jednej z warstw. Ramka dla pliku jest wysyłana tylko wtedy, gdy jego zestaw różni się od tego, o którym ten klient był ostatnio informowany, więc żądanie, które ponownie wylicza te same ustalenia, niczego nie wysyła; pierwsza ramka pliku oraz ramka opróżniająca zestaw pliku są różnicami i są zawsze wysyłane.

Prośba skierowana do samego procesu o zatrzymanie dociera do demona na tych samych zasadach. Przerwanie z terminala lub żądanie zakończenia od nadzorcy albo środowiska uruchomieniowego kontenerów rozpoczyna to samo wygaszanie, które rozpoczyna aggrega/shutdown: trwające żądania kończą się, nowe są odrzucane, po czym demon kończy działanie. Drugie żądanie natychmiast kończy proces. Klient uruchamiający demona może go zatrzymać w dowolny z tych sposobów, a klient zatrzymujący go przez protokół i klient wysyłający mu sygnał otrzymują to samo wygaszanie.

Walidacja na żywo

Przy każdym aggrega/validate demon waliduje bufor edytora względem schematu dokumentu i zwraca diagnostyki wskazujące na niepoprawny klucz — ten sam werdykt, jaki dałaby kompilacja, dla niezapisanej treści. Żądanie, które nie wysyła content, pyta o plik w postaci zapisanej na dysku; content wysłane jako puste oznacza pusty bufor, a nie żądanie pliku. Plik wysłany bez treści musi należeć do obszaru roboczego i dać się odczytać — plik spoza obszaru roboczego, plik osiągnięty przez dowiązanie prowadzące poza niego lub plik, którego nie ma, jest odrzucany z kodem invalid-params. Encje katalogu, Aggregates, Manifests i Releases są rozpoznawane po apiVersion i kind. Dwa dokumenty, które nie mają takiego nagłówka — konfiguracja obszaru roboczego .aggrega-config.yaml oraz plik blokady encji Release wskazanej w żądaniu — są rozpoznawane zamiast tego po nazwie pliku, dzięki czemu zbędny lub źle ukształtowany klucz w którymkolwiek z nich również jest podkreślany na żywo. Pliki, które nie są dokumentami Aggrega — szablony chartów Helm, pliki Compose, manifesty Kubernetes oraz pliki .lock innych ekosystemów, takie jak Cargo.lock czy flake.lock — nie otrzymują diagnostyk; demon nigdy nie raportuje o obcych plikach.

Symbol zastępczy, który wciąż trzeba uzupełnić, jest wskazywany przy swoim kluczu wraz z tym, czego wymaga. Encja katalogu rodzaju, który aggrega validate sprawdza jako pojedynczą encję, jest również odczytywana pod kątem wymaganych wartości pozostawionych jako pusty ciąg, w taki sam sposób, w jaki odczytuje je to polecenie, więc demon wskazuje każdy symbol zastępczy, który polecenie wskazuje dla tych samych bajtów. Każdy symbol zastępczy to jeden wpis: jego message mówi, że klucz jest symbolem zastępczym wciąż do uzupełnienia, suggest mówi, czego wymaga wartość, a keyPath zawiera ścieżkę klucza zapisaną z kropkami. Wpis zastępuje własne zgłoszenie schematu dla tej pustej wartości, a każde inne zgłoszenie dotyczące dokumentu jest raportowane tak, jak raportuje je sprawdzenie schematu. Wskazywany jest także symbol zastępczy, który schemat dopuszcza jako pusty, choć sprawdzenie schematu nic o nim nie raportuje — w praktyce będą to capability i implements szkicu encji Recipe lub FeatureRecipe. Tam, gdzie sprawdzenie schematu również odrzuca dokument, każdy wpis zawiera kod tego sprawdzenia, E0215, a tam, gdzie je akceptuje, wpisy nie zawierają kodu: są to te same identyfikatory, które zawiera raport polecenia dla tych bajtów. Wpis jest rysowany przy kluczu zawierającym pustą wartość, w wierszu, w którym wskazuje go polecenie — nawet przy kluczu, którego własna nazwa zawiera kropkę, takim jak etykieta component.aggrega.ai/type, gdzie zgłoszenie sprawdzenia schematu dotyczące tego klucza jest rysowane przy kluczu, który go obejmuje — a keyPath podaje pełną nazwę klucza. Obowiązuje to niezależnie od tego, czy żądanie wskazuje encję Release, ponieważ jest to pytanie, na które dokument odpowiada sam, a dokument, któremu wciąż brakuje wartości, nie jest jeszcze sprawdzany pod kątem konwencji publikowania: ta warstwa jest dla niego czyszczona, tak jak dla dokumentu, którego kształt schemat odrzuca.

Każde żądanie wskazuje encję Release, której dotyczy, a demon nie przechowuje własnej. Sprawdzenia semantyczne rozwiązują domknięcie zależności tej encji Release i odczytują jej plik blokady w poszukiwaniu przypięć — lub, w przypadku encji katalogu, odczytują katalogi, z którymi ta encja Release jest budowana, jak opisuje następny akapit — więc dwa żądania wskazujące dwie Releases otrzymują odpowiedź dotyczącą encji Release wskazanej przez każde z nich. Nic nie przechodzi między nimi: nie ma wybranej encji Release do zmiany, a zmiana encji Release, względem której odbywa się walidacja, to po prostu inna wartość w następnym żądaniu, a nie coś, o czym demonowi trzeba kazać zapomnieć.

Encja katalogu wskazana razem z encją Release jest sprawdzana jako pojedyncza encja, w kategoriach tej encji Release. file zawierający Component, Feature, Recipe, FeatureRecipe lub Plugin, wysłany z release, przechodzi sprawdzenie, które wykonuje aggrega validate <path> --release <release>, na niezapisanym buforze edytora: jego odwołania — Component, który implementuje Recipe, biblioteka, do której odwołuje się filar — są rozwiązywane przez katalogi, które konfiguracja obszaru roboczego przypisuje tej encji Release, więc jeden plik może być poprawny w kategoriach encji Release, która jest z nim budowana, i niepoprawny w kategoriach encji Release, której katalogi nie zawierają tego, do czego się odwołuje. Jest to werdykt, który wiersz poleceń i narzędzie validate z aggrega mcp dają dla tej samej encji przy tej samej encji Release, i podobnie jak one nie przechodzi żadnego domknięcia ani nie odczytuje pliku blokady. Blokujące zgłoszenie to jeden wpis błędu słowami samego sprawdzenia i z jego kodami, rysowany przy kluczu, który wskazuje w encji, a jeśli nie wskazuje żadnego, przy kluczu kind: encji, jak opisuje Co zawiera wpis diagnostyki — chyba że kompilacja już raportuje ten błąd w pliku, a wtedy jedynym raportem jest wpis kompilacji; ostrzeżenie zgłoszone przez sprawdzenie podczas odczytu katalogu to wpis ostrzeżenia przed nim; czyste sprawdzenie nad katalogami, które wszystkie istnieją, nie daje żadnego wpisu. Niespełniona asercja — taka, która wywołuje fail, w encji Recipe lub w encji Component, którą ona implementuje — nie jest tu blokującym zgłoszeniem, lecz wpisem ostrzeżenia, słowami sprawdzenia i z jego kodami, zakończonym zdaniem A Release must satisfy this assertion before a build of it can pass. i rysowanym tam, gdzie byłoby zgłoszenie blokujące: asercja encji Recipe przy własnym kluczu tej asercji w assertions, asercja encji Component przy kluczu kind: encji Recipe. Podobnie jak zgłoszenie blokujące ustępuje ono wpisowi kompilacji raportującemu ten sam błąd w pliku. Sprawdzenie buduje encję wokół symboli zastępczych i wartości domyślnych schematu, a nie wartości ustawianych przez encję Release, więc nie potrafi odróżnić asercji czekającej na encję Release od asercji błędnej i pozostawia werdykt kompilacji, która raportuje tę samą asercję jako błąd (niespełniona asercja jest ostrzeżeniem). Katalog, który konfiguracja obszaru roboczego podaje dla encji Release, a który nie jest katalogiem — na przykład nic w tym miejscu nie istnieje — zatrzymuje sprawdzenie: plik otrzymuje jeden wpis błędu zamiast werdyktu sprawdzenia, czyli odmowę, którą każde polecenie daje temu katalogowi, wskazującą wpis, plik konfiguracji i wiersz, który go wymienia, oraz ustawienie (Skąd odczytywane są encje lokalne). release, który nie wskazuje żadnego pliku lub wskazuje katalog, otrzymuje w pliku odpowiedź w postaci zdania, którym odrzuca go wiersz poleceń, zamiast sprawdzenia w kategoriach obszaru roboczego. To, czego kompilacja pojedynczej encji nie może zastąpić, jest oceniane tak, jak ocenia to wiersz poleceń, a to, co wiersz poleceń pomija lub czego nie sprawdza, nie daje tu żadnego wpisu — zob. czego nie sprawdza poprawność pojedynczej encji oraz, dla encji Recipe, której szablon odczytuje wartość dostarczaną wyłącznie przez krawędź topologii lub dołączone poświadczenie, poprawność pojedynczej encji. Własna encja Aggregate encji Release, Manifest, Release ani biblioteka nie są sprawdzane pojedynczo, ponieważ sprawdzenie pojedynczej encji nie przyjmuje tych rodzajów; podlegają one opisanym wyżej sprawdzeniom domknięcia. Bufor zawierający treść Workload jest odczytywany jako YAML niebędący dokumentem Aggrega, ponieważ taka treść jest zapisywana w polu workload: encji Recipe lub FeatureRecipe i jest sprawdzana tam, gdzie się znajduje; wiersz poleceń i narzędzie validate, którym przekaże się plik Workload przez ścieżkę, sprawdzają jego kształt samodzielnie.

Wskazanie encji Release jest opcjonalne, a odpowiedź mówi, o który z dwóch wariantów zapytano. Po wskazaniu encji Release otrzymuje się wszystko, co opisano powyżej. Bez wskazania otrzymuje się kontrole, na które dokument odpowiada sam — czy się parsuje, czy jego własny kształt jest dopuszczalny oraz, dla encji katalogu rodzaju walidowanego jako pojedyncza encja, jakie symbole zastępcze nadal jest winien — bez rozwiązywania encji Release, bez przechodzenia domknięcia i bez odczytu pliku blokady; odpowiedź zawiera wtedy checked: "document". Po wskazaniu encji Release tego klucza nie ma, ponieważ taka odpowiedź jest pełnym werdyktem metody i nie ma czego zastrzegać.

Należy odczytywać ten klucz, a nie wnioskować z diagnostyk, ponieważ obie odpowiedzi mogą wyglądać identycznie. Poprawnie sformułowany dokument walidowany bez encji Release zwraca pustą listę diagnostyk, czyli dokładnie to samo, co czysty pełny werdykt, więc checked jest jedynym, co odróżnia „nic nie jest nie tak” od „nie sprawdzono niczego, co wymaga encji Release”. Z tej samej zasady wynika jedna konsekwencja: plik blokady jest rozpoznawany po powiązaniu z encją Release wskazaną w żądaniu, więc żądanie bez wskazania nie rozpoznaje żadnego pliku blokady i niczego w nim nie zgłasza.

Obszar roboczy bez żadnej encji Release otrzymuje odpowiedź, a nie odmowę, i właśnie dzięki temu reszta demona pozostaje w nim użyteczna. Walidacja zasila pamięć podręczną parsowania, z której korzystają wszystkie inne operacje na plikach, więc repozytorium zawierające wyłącznie katalog, szkielet z pojedynczą encją Aggregate czy katalog roboczy nadal mają podpowiedzi po najechaniu, uzupełnianie, przejście do definicji, odwołania, implementacje i diagnostyki z pamięci podręcznej. Odmowa odebrałaby je wszystkie, i to właśnie w obszarach roboczych, w których klient nie ma encji Release do wskazania.

Co zawiera wpis diagnostyczny

Każdy wpis określa swoje położenie przez line i column, liczone od 1 w kodowaniu pozycji wynegocjowanym podczas uzgadniania połączenia, i dodaje end_line oraz end_column, gdy obejmuje cały token. message to tekst, który klient pokazuje użytkownikowi, severity go klasyfikuje, a source wskazuje, która z warstw demona go zgłosiła, jak opisano powyżej.

Warstwy odpowiadają na różne pytania o jeden plik, więc wpisy z każdej z nich mogą stać w tym samym wierszu, nie będąc duplikatami: jeden mówi, że wdrożenie jest niepoprawne, inny, że encji nie można opublikować. Klient, który pokazałby je jako jedną listę, zgłosiłby jeden problem dwukrotnie, a odczyt source pozwala je rozdzielić.

Położenie wpisu zależy od tego, czego dotyczy, a nie od tego, która warstwa go zgłosiła. Ustalenie dotyczące czegoś, co napisał autor, jest umieszczane przy kluczu, pod którym to napisał, więc edytor rysuje je tam, gdzie należy wprowadzić zmianę. Ustalenie dotyczące kształtu wdrożonej topologii wskazuje komponent i klucz dostarczenia zamiast wiersza — są to współrzędne we wdrożonej topologii, a nie w dokumencie — więc jest rysowane przy kluczu kind: dokumentu, a swoje współrzędne podaje w komunikacie. Oba rodzaje trafiają do warstwy aggrega-build, ponieważ kompilacja zgłasza oba. Odmowa zgłoszona przez kompilację podczas renderowania również trafia do tej warstwy, w dokumencie, na który sama odmowa wskazuje — encja Workload niespełniająca swoich kontroli przy kluczu workload swojej encji Recipe, niespełniona asercja encji Recipe przy własnym kluczu tej asercji, wpis odrzucony przez kompozycję grafu przy kluczu, pod którym zapisała go encja Release lub Aggregate, oraz każde ustalenie odmowy łączącej kilka z nich przy własnym dokumencie i kluczu — a gdy nie wskazuje żadnego dokumentu, przy kluczu kind: encji Aggregate; opisuje to sekcja Odmowa zgłoszona podczas renderowania. Dlatego klient umieszcza każdy wpis według jego własnych line i column i nigdy nie wnioskuje o położeniu z warstwy.

Ustalenie, które nie wskazuje żadnego klucza obecnego w dokumencie, jest rysowane przy kluczu identyfikującym dokument. Ustalenie, które własne kontrole dokumentu zgłaszają w sprawie jego treści, ustalenie kontroli pojedynczej encji oraz ostrzeżenie lub odmowa zgłoszone przez kompilację są rysowane przy kluczu, który wskazują; gdy nie wskazują żadnego lub wskazują klucz, którego dokument nie zawiera, są rysowane przy kluczu kind: dokumentu albo przy jego metadata.name, gdy nie deklaruje on kind:, a na początku pliku tylko wtedy, gdy dokument nie deklaruje żadnego z nich lub się nie parsuje. Dokument często zaczyna się od komentarza — każdy plik katalogu ma nagłówek licencyjny — i wpis narysowany w jego pierwszym wierszu znalazłby się na tym komentarzu i wyglądał na błąd w nim, podczas gdy tożsamość dokumentu to wiersz napisany przez autora. Wpis dotyczący czegoś innego niż treść dokumentu jest umieszczany na początku pliku: wpis Dependencies: o zależnościach encji Release, etap, który zatrzymał się bez wskazania czegokolwiek w dokumencie, rozbieżny plik blokady, odwołanie, które renderowanie musiało odrzucić, encja Release, której nie udało się wczytać — podobnie wpis aggrega-lint, którego reguła nie wyznaczyła wiersza. Tam, gdzie położenie jest podawane, a nie rysowane, ustalenie bez klucza nadal go nie ma: odpowiedź błędu odmowy, która nie wskazuje klucza, zawiera w data sam dokument.

Z tej samej zasady wynika, w którym dokumencie wpis jest publikowany. Walidacja wskazująca encję Release dotyczy encji Aggregate tej encji Release, samej encji Release, dokumentu każdego modułu importowanego przez encję Aggregate oraz encji Manifest wskazanej przez encję Release. Ustalenie umieszczone w encji Release — odmowa wpisu, który encja Release zapisuje przy jednym z połączeń komponentu, wymiarowania, które nadaje temu połączeniu, załącznika, który tam wypełnia lub wymiaruje, połączenia, które tworzy, encji Feature, którą tylko encja Release dołącza do komponentu lub granicy, albo infra, które nadaje załącznikowi — jest publikowane przy walidacji dokumentu encji Release, przy kluczu w encji Release, który je zapisał, a w encji Aggregate wcale. Ustalenie umieszczone we własnym dokumencie modułu — odmowa tego, co deklaruje jeden z komponentów modułu, gniazda, które łączą jego załączniki, jego wartości lub wartości przy jego własnych połączeniach — jest publikowane przy walidacji dokumentu tego modułu, przy kluczu, który je tam zapisał, a w encji Aggregate wcale. Ustalenie dotyczące tabeli mapowań encji Manifest — wpis mapujący typ na encję Recipe lub FeatureRecipe, która go nie implementuje, wpis, którego przypięcia wersji nie da się sparsować, lub zmapowany typ, którego łańcucha extends nie da się prześledzić — jest publikowane przy walidacji tej encji Manifest, przy kluczu wpisu mapowania, którego dotyczy, a w encji Aggregate wcale; jeśli otwarty tekst encji Manifest nie zapisuje tego wpisu — wpisu dziedziczonego przez jej własne extends albo usuniętego przez niezapisaną edycję — ustalenie jest publikowane w pierwszym wierszu encji Manifest. Każde inne ustalenie zgłoszone przy walidacji tej encji Release jest publikowane w encji Aggregate, w tym ustalenia na poziomie zależności, które nie wskazują żadnego dokumentu obszaru roboczego — wycofane odwołanie lub plugin, encja Component lub Feature z katalogu, której łańcuch extends się nie rozwiązuje lub której schemat jest nieprawidłowy, plugin bramki, z którym rejestr zaufania jest niezgodny, instancja komponentu, której nie rozwiązuje żadne mapowanie, encja Recipe lub FeatureRecipe, której dostawca nie potrafi wyrenderować zadeklarowanego przez nią rodzaju wejścia, oraz porady dotyczące nakładania się filarów schematu i zawężania przy rozszerzaniu. Dzięki temu ustalenie dotyczące tego, co napisał operator, pojawia się, gdy encja Release jest otwarta, ustalenie dotyczące tego, co deklaruje moduł — gdy ten moduł jest otwarty, a ustalenie dotyczące mapowania — gdy otwarta jest encja Manifest, niezależnie od tego, który etap kompilacji je zgłosił; edytor walidujący każdy otwarty dokument względem encji Release pokazuje tam każde z nich. Encja Release, której zależności w ogóle nie dają się rozwiązać, nie zgłasza żadnego z tych ustaleń, a niepowodzenie ich rozwiązania jest jednym wpisem na początku własnego dokumentu encji Release oraz każdego innego dokumentu walidowanego względem niej, który demon rozpoznaje, jak opisuje Walidacja na żywo, i którego nie sprawdza jako pojedynczej encji — jej encji Aggregate, encji Manifest, biblioteki, innej encji Release, konfiguracji obszaru roboczego — z prefiksem Dependencies: i z własnym opisem rozwiązywania tego, co je zatrzymało. We własnym dokumencie encji Release wpis jest tym opisem i niczym więcej. W każdym innym dokumencie najpierw informuje, że dokument jest sprawdzany względem tej encji Release, i podaje jej nazwę tak, jak wskazuje ją żądanie — Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved:, a po nim opis — ponieważ nic w tym dokumencie nie mówi, względem której encji Release go sprawdzono: edytor sprawdzający każdy otwarty dokument względem jednej wybranej encji Release umieszcza ten wpis w dokumentach, które nie mają z nią nic wspólnego, a nazwa pozwala ustalić, że przyczyną jest ten wybór. Plik, którego demon nie rozpoznaje, nie ma takiego wpisu, niezależnie od wskazanej z nim encji Release.

Odpowiedź zawiera każdą warstwę obecną w pliku, niezależnie od tego, jak daleko doszła walidacja. Odpowiedź aggrega/validate to cały bieżący stan pliku: to, co znalazła ta walidacja, wpisy aggrega-build opublikowane w pliku przez kompilację, podgląd lub żądanie grafu oraz ustalenia dotyczące konwencji publikowania, każde pod własnym source. Walidacja, która zatrzymuje się na buforze — taka, który się nie parsuje, lub dokument, którego kopertę schemat odrzuca — odpowiada tak samo: zgłasza własne ustalenie i pozostawia w pliku wszystkie wpisy kompilacji, ponieważ niczego się o kompilacji nie dowiedziała. Dzięki temu klient może zastąpić to, co przechowuje dla pliku, warstwa po warstwie, na podstawie dowolnej odpowiedzi.

Jeden błąd jest zgłaszany raz. Własna walidacja dokumentu i build mogą znaleźć w nim ten sam błąd: sprawdzenie pojedynczej encji renderuje encję Recipe, którą renderuje także build, walidacja składa graf, który składa build, a encja Release, której zależności nie dają się rozwiązać, nie przechodzi obu. Dopóki build zgłasza taki błąd w dokumencie, walidacja tego dokumentu nie zgłasza go po raz drugi: wpis aggrega nazywający ten sam warunek — ten sam code — co odmowa buildu w tym samym dokumencie, umieszczony w tym samym zakresie lub przy żadnym własnym kluczu — narysowany tam, gdzie rysowany jest wpis nienazywający klucza, albo na początku pliku — jest pomijany w każdej odpowiedzi i każdej publikacji dla tego dokumentu, a zgłoszenie buildu pozostaje jedyne. Zgłoszeniem buildu jest wpis odmowy w warstwie aggrega-build; albo, dla aggrega/build, aggrega/buildPreview lub aggrega/irGraph odrzuconych z 1004, ponieważ zależność nie daje się rozwiązać, sama ta odpowiedź — której nic nie publikuje — w dokumencie wskazanym przez jej data.file, w przeciwnym razie przez jej data.lockfile, w przeciwnym razie w encji Release nazwanej w żądaniu, przy czym liczy się najnowsza taka odpowiedź dla danej encji Release. Walidacja zachowuje to, co znalazła: gdy żaden build nie zgłasza już błędu — następne uruchomienie publikuje warstwę bez niego, następna odpowiedź buildu, podglądu lub grafu dla tej encji Release jest jakakolwiek inna albo łączy się klient, któremu nie udzielono takiej odpowiedzi 1004 — własny wpis dokumentu jest znów zgłaszany, a tam, gdzie żaden build nie został uruchomiony, nic nie jest pomijane. Wpis aggrega umieszczony przy kluczu, przy którym nie stoi żadna odmowa buildu, pozostaje, nawet jeśli nazywa ten sam warunek, ponieważ może to być drugi błąd tego rodzaju, którego build nie zgłosił.

code to stabilny, przeznaczony do dopasowywania maszynowego kod tego, co zgłasza wpis, dzięki czemu klient może rozgałęziać się na jego podstawie bez dopasowywania tekstu komunikatu. Jeden klucz przenosi kod niezależnie od tego, kto go nadał, a source mówi, z jakim rodzajem ma się do czynienia, ponieważ warstwy nazywają rzeczy za pomocą różnych słowników.

  • We wpisie aggrega — ustaleniu dotyczącym napisanych dokumentów — kod jest ciągiem, pod którym zarejestrowano warunek, zapisanym jako pakiet deklarujący, a po nim reguła w kebab-case. Jest to ta sama wartość, którą konsument w Go odczytuje za pomocą CodeOf; jej postać i dopasowywalną powierzchnię opisuje dokumentacja sentineli błędów.
  • We wpisie aggrega-build — ostrzeżeniu zgłoszonym przez build — kod jest tym, co nadało miejsce zgłoszenia, a ta warstwa przenosi ostrzeżenia z dwóch różnych słowników, ponieważ build zgłasza ostrzeżenia o dwóch różnych rodzajach rzeczy. Ostrzeżenie o kształcie wdrożonej topologii ma kod klasy, taki jak unsupported-field, nadany tam, gdzie zostało zgłoszone, czy to w pluginie renderującym, czy w samym renderowaniu; kod klasy nazywa klasę ostrzeżeń, a nie zarejestrowany warunek, więc nie ma wiersza w dokumentacji sentineli, a dokumentacja ostrzeżeń opisuje klasę unsupported-field i flagę, która ją wycisza. Ostrzeżenie o napisanych dokumentach — nazwie różniącej się jedną edycją od zadeklarowanej, parametrze, którego nic nie odczytuje — ma ciąg, pod którym zarejestrowano jego warunek, w tej samej postaci co wpis aggrega i z wierszem w dokumentacji sentineli. Tak czy inaczej kod nazywa to, czym jest ustalenie, a nie to, kto je znalazł, więc pojedyncza klasa dociera pod jednym kodem niezależnie od liczby miejsc, które ją zgłaszają, i to odczytanie kodu, a nie warstwy, mówi, z którym z dwóch rodzajów ma się do czynienia. Odmowa, na której build zatrzymał się podczas renderowania, jest jedynym wpisem w tej warstwie, który nie jest ostrzeżeniem, i w ten sam sposób ma ciąg, pod którym zarejestrowano jej warunek.
  • We wpisie aggrega-lint — ustaleniu dotyczącym konwencji publikowania — kod jest tożsamością ustalenia: tożsamością reguły, która je wygenerowała, lub, w przypadku ustalenia, które nie wskazuje żadnej reguły — a takie może zgłosić własny linter pod własnym kodem — tym właśnie kodem. Jest to identyfikator, który aggrega lint wypisuje w wierszu ustalenia, po krótkim kodzie, jeśli taki istnieje, oraz wartość, którą aggrega lint --output json przenosi dla tego samego ustalenia jako ruleId lub jako code w przypadku ustalenia niewskazującego żadnej reguły. Jedno ustalenie zachowuje jedną tożsamość na wszystkich powierzchniach, więc klient, który grupuje lub wycisza regułę w edytorze, grupuje i wycisza tę samą regułę w terminalu. Każda reguła zestawu reguł lintera publikowania deklarowanego przez Aggrega jest zarejestrowana jako warunek pod tą tożsamością, dlatego figuruje w tabeli wszystkich warunków pod krótkim kodem, który aggrega lint wypisuje na początku wiersza tego samego ustalenia, a aggrega lint --output json przenosi w nim jako shortCode. Reguła własnego lintera, której Aggrega nie deklaruje, nie wskazuje żadnego zarejestrowanego warunku; nie wskazuje go też ustalenie niewskazujące żadnej reguły, nawet jeśli jego własny kod zapisuje tożsamość reguły deklarowanej przez Aggrega — dlatego żadne z nich nie figuruje w tej tabeli. Reguły opisano w dokumentacji polecenia aggrega lint w części referencyjnej.

Niezależnie od warstwy klucz odpowiada na jedno pytanie — czym to jest, w kategoriach, które maszyna może dopasować — więc rozszerzenie edytora, które wyróżnia, grupuje lub wycisza jedną klasę ustaleń, opiera się na kodzie i działa dalej, gdy zmieni się brzmienie komunikatu.

Należy zwrócić uwagę, który obiekt co przenosi: tu jest to ciąg we wpisie diagnostycznym, odrębny od liczbowego code w kopercie błędu JSON-RPC opisanej poniżej w sekcji Kody błędów. Odpowiedź przenosi jedno albo drugie, nigdy oba w jednym miejscu.

Klucz jest pomijany tam, gdzie nic, co wygenerowało wpis, nie nadało kodu, i każdy rodzaj ma taki przypadek. Bufor, którego żaden parser YAML nie odczyta, zgłasza własny tekst parsera bez kodu, ponieważ nie stoi za nim żaden warunek samego Aggrega; etap, który zgłasza niepowodzenie bez nazwania warunku, również nie ma czego zgłosić; a ostrzeżenie, któremu zgłaszający nie nadał kodu, przychodzi bez niego. Dlatego code należy traktować jako opcjonalny, tak samo jak end_line i end_column, i rozgałęziać się na jego podstawie tylko wtedy, gdy jest obecny. Kod jest tym, co diagnostyka zgłasza, a nigdy tym, co ją wybiera: żadne żądanie nie przyjmuje kodu, a wpisanie go z powrotem we własny kod daje ciąg, a nie sposób dopasowania.

Identyfikator dopasowywany przez program i identyfikator cytowany przez człowieka

Warunek ma dwa identyfikatory, przeznaczone dla dwóch różnych odbiorców. code to ten opisany powyżej: kwalifikowany i z łącznikami, dzięki czemu program rozgałęziający się na jego podstawie czyta się zgodnie z tym, co znaczy. shortCode to litera E i cztery cyfry — E0164 — i to on jest tym, który człowiek może odczytać na głos, wpisać w pole wyszukiwania lub wkleić do zgłoszenia. Oba nazywają ten sam warunek i żaden nie jest skrótem drugiego.

To, po który sięgnąć, wynika z tego, kto czyta. W rozszerzeniu należy dopasowywać po code; autorowi należy pokazywać shortCode. Rozszerzenie pokazujące tylko code zostawia czytelnika z identyfikatorem przeznaczonym dla programu, a takie, które dopasowuje po shortCode, dopasowuje po numerze, który nic nie mówi o warunku. Ten podział jest powodem, dla którego przesyłane są oba, a nie jeden.

codeDescription wskazuje miejsce publikacji warunku, przesyłane jako { "href": … }, czyli własna struktura protokołu dla odnośnika, który można otworzyć, aby dowiedzieć się więcej o diagnostyce. Edytor obsługujący protokół zamienia go w element „dowiedz się więcej” bez konieczności uczenia go czegokolwiek o Aggrega, a żaden klient nie potrzebuje kopii objaśnień. Adres prowadzi do opublikowanej listy wszystkich warunków, gdzie wpis dla danego shortCode nazywa warunek i prowadzi dalej do omówienia poprawki w dokumentach.

Sam opis nie znajduje się we wpisie i jest to celowe. Diagnostyka jest emitowana przy każdej edycji, więc objaśnienie dołączane do każdej z nich publikowałoby te same akapity przy każdym naciśnięciu klawisza czytelnikowi, który zwykle już je przeczytał. Klient, który chce tekstu, prosi o niego raz, za pomocą aggrega/explainError opisanego poniżej; klient, który potrafi otworzyć odnośnik, nie potrzebuje żadnego z nich.

Oba klucze są obecne dokładnie wtedy, gdy wpis nazywa zarejestrowany warunek, a w przeciwnym razie oba są nieobecne. Decyduje o nich to, co stoi za wpisem, a nie to, która warstwa go opublikowała, dlatego należy odczytywać klucze, a nie warstwę:

  • Wpis nazywający zarejestrowany warunek zawiera wszystkie trzy. shortCode daje się rozwiązać, a odnośnik prowadzi do listy, w której się go rozwiązuje.
  • Wpis, którego kod nazywa klasę, zawiera tylko code. Klasa ostrzeżenia renderowania oraz tożsamość wyniku sprawdzenia konwencji z własnego lintera — reguły, której Aggrega nie deklaruje, lub kodu, który zawiera wynik nienazywający żadnej reguły — to prawdziwe identyfikatory, według których można grupować i wyciszać, i żaden z nich nie jest zarejestrowanym warunkiem — nie ma więc numeru do zacytowania ani niczego pod adresem, co by je opisywało. Odnośnik wysłany mimo to prowadziłby do strony, która nie dotyczy problemu czytelnika, dlatego żaden nie jest wysyłany. Taki jest zwykły kształt w warstwie aggrega-build, choć ostrzeżenie kompilacji, które nazywa zarejestrowany warunek, zawiera wszystkie trzy, jak każde inne. W warstwie aggrega-lint zwykłym kształtem jest pełny zestaw: reguła z zestawu reguł lintera publikacji deklarowanego przez Aggrega jest zarejestrowanym warunkiem, więc jej wynik zawiera ten sam shortCode, który aggrega lint wypisuje na początku wiersza wyniku, a obok niego odnośnik.
  • Wpis, który niczego nie nazywa, nie zawiera żadnego identyfikatora.

Trzy przypadki można więc rozróżnić po samych kluczach: brak code oznacza, że nie ma czego nazwać, code bez shortCode obok oznacza identyfikator, którego nie da się dalej rozwiązać, a pełny zestaw oznacza identyfikator, o którym można gdzieś przeczytać. Oba nowe klucze należy traktować jako opcjonalne, tak samo jak code, a czytelnikowi proponować coś do otwarcia tylko tam, gdzie dotarło codeDescription.

Rozwijanie kodu zawartego w diagnostyce

aggrega/explainError zamienia dowolny z dwóch identyfikatorów warunku na to, co kompilator o nim deklaruje, oraz na opublikowane wpisy objaśniające poprawkę w dokumentach. To to samo rozwinięcie, które aggrega explain wykonuje w terminalu, a narzędzie explain-error dla asystenta, i wszystkie trzy odpowiadają z jednego miejsca, więc kod rozwinięty tutaj i ten sam kod rozwinięty gdzie indziej to jedna odpowiedź, a nie trzy, które przypadkiem są zgodne.

code jest wymagany i przyjmuje dowolny z identyfikatorów — shortCode zawarty w diagnostyce lub code obok niego — ponieważ klient mający jeden z nich nie może uzyskać drugiego bez zapytania. Pusta wartość jest odrzucana z informacją, co należy wysłać.

Odpowiedź zawsze zawiera shortCode, code i message: dwa identyfikatory warunku oraz zdanie, od którego zaczyna się każda diagnostyka go nazywająca. Są one zadeklarowane w pliku binarnym, więc docierają bez sieci i bez pamięci podręcznej, dzięki czemu można odpowiedzieć nawet obszarowi roboczemu bez dokumentacji. reference to ten sam adres, który zawiera codeDescription diagnostyki, dla klienta, który woli odesłać czytelnika do dokumentacji, niż renderować tekst.

entries zawiera opublikowane omówienie, każdy wpis jako otwierający go heading i znajdujące się pod nim body, w kolejności, w jakiej dokumentacja sama łączy je z warunkiem. Jest pomijane, gdy omówienia nie dało się dodać, a wtedy note podaje powód: opublikowana strona nie dokumentuje jeszcze żadnego wpisu dla tego warunku albo ten obszar roboczy nie może odczytać dokumentacji — maszyna nie ma jej kopii lub ma tylko taką, którą odrzuca sprawdzenie podpisu obszaru roboczego. W obu przypadkach warunek powyżej pozostaje — odpowiedź nie jest błędem, a klient pokazuje to, co dotarło, wraz z notatką. entries i note nigdy nie docierają razem.

Kod, którego nic nie rozwiązuje, jest odrzucany, a nie zwracany jako warunek o samych pustych polach, a każde odrzucenie mówi, który to przypadek: kod, pod którym nie zarejestrowano żadnego warunku, numer, który kiedyś nazywał warunek i nigdy nie nazwie innego, lub kod, którego ten plik binarny nie deklaruje, gdy opublikowanej listy w ogóle nie dało się odczytać — ostatni przypadek pozostawia otwarte obie poprawki, ponieważ lista opublikowana dla innej wersji może nazywać warunek, którego ten plik binarny nie deklaruje.

Dokumentacja jest odczytywana z pakietu zapisanego w pamięci podręcznej dla obszaru roboczego wskazanego w żądaniu, pobieranego przy pierwszym użyciu, gdy go brakuje, i jest to jedyny powód, dla którego to żądanie sięga do rejestru — zob. Sięganie do rejestru i zapis. Nic nie jest zapisywane w obszarze roboczym. Żadna walidacja tego nie wyzwala: rozwinięcie następuje, ponieważ zażądało go żądanie, więc rejestr nigdy nie jest odpytywany podczas walidacji lub inspekcji dokumentu.

Publikowanie konwencji: na żądanie i przy każdej edycji

Demon odpowiada na dwa różne pytania dotyczące encji katalogu i są to te same pytania, na które w terminalu odpowiadają aggrega validate i aggrega lint: czy wdrożenie jest poprawne oraz czy encja nadaje się do publikacji według konwencji katalogu. Walidacja zawsze odpowiada na pierwsze pytanie. Na drugie odpowiada tylko wtedy, gdy się o to poprosi.

aggrega/lint prosi o to wprost. Należy wysłać entity dla jednej encji katalogu, release dla każdej encji osiąganej przez domknięcie zależności tej encji Release albo żadnego z nich, aby sprawdzić każdą encję w skonfigurowanych katalogach — to trzy zakresy, które ma polecenie. Wysłanie jednocześnie entity i release wskazuje dwa różne przedmioty i jest odrzucane. Odpowiedź zawiera checked, liczbę dokumentów encji objętych przebiegiem, oraz files, wyniki pogrupowane według dokumentu, którego dotyczą, i uporządkowane według ścieżki, przy czym wpisy każdego pliku mają opisany wyżej kształt diagnostyki. halted mówi, czy werdykt samego przebiegu odmawia publikacji.

Niewysłanie żadnego z nich sprawdza cały katalog tak, jak robi to aggrega lint bez argumentu. Obszar roboczy, którego konfiguracja nie podaje własnych katalogów dla encji Release, jest sprawdzany raz, w obrębie własnych katalogów, a odpowiedź jest taka, jak opisano wyżej. Obszar roboczy, który wymienia Releases w workspace.releases, jest sprawdzany raz dla każdej encji Release w nim, w obrębie katalogów, które ta encja Release odczytuje, i nigdy w obrębie wszystkich naraz — dzięki temu warianty katalogu trzymane obok siebie, po jednym na Release, są każdy sprawdzane w kategoriach encji Release, która je odczytuje. Odpowiedź zawiera wtedy także passes, po jednym wpisie na przebieg: releases, czyli Releases, dla których go uruchomiono, każdą względem katalogu głównego obszaru roboczego, przy czym Releases odczytujące te same katalogi dzielą jeden wpis; catalogDirs, odczytane katalogi, zapisane tak, jak files zapisuje ścieżkę, i puste dla encji Release, która nie odczytuje żadnego, co jest zgłaszane zamiast powodować niepowodzenie pozostałych; oraz własne liczniki i files tego przebiegu, które mówią, dla której encji Release znaleziono dany wynik. checked, liczniki i files wokół nich obejmują wszystkie przebiegi razem, więc klient, który nie odczytuje passes, i tak odczytuje cały przebieg. Przebieg, w którym żaden przejazd nie ma katalogu do odczytania, jest odrzucany, a nie zgłaszany jako czysty katalog.

Ustawienie prePublish razem z entity porównuje tę encję z jej poprzednio opublikowaną wersją i klasyfikuje względem niej proponowane podniesienie wersji. Jest to jedyny tryb w tym miejscu, który sięga do rejestru, i działa, ponieważ żądanie go wskazało: operację sięgającą na zewnątrz dopuszcza to, że wywołujący o nią poprosił. Ma sens tylko z entity, więc prePublish bez encji jest odrzucane.

aggrega/lint nie publikuje niczego do sesji. Odpowiada w sprawie przedmiotu, który otrzymał, a zapisanie jego wyników na liście problemów edytora zastąpiłoby to, co walidacja opublikowała dla plików, których żądanie nigdy nie objęło. W żadnym trybie nic nie jest zapisywane na dysku.

serve.lint_on_validate uruchamia te same reguły przy każdej walidacji i jest wyłączone, dopóki się go nie włączy. Należy je włączyć w .aggrega-config.yaml, w obszarze roboczym, dla którego encji potrzebne są wskazówki:

serve:
lint_on_validate: true

Nie ma dla niego flagi, ponieważ pytanie, na które odpowiada, dotyczy własnej treści obszaru roboczego, a osobą, która je zadaje, jest autor obszaru roboczego, a nie ten, kto uruchomił demona. Gdy jest włączone, walidacja encji katalogu publikuje również wyniki konwencji pod źródłem aggrega-lint; gdy jest wyłączone — domyślnie — walidacja zgłasza wyłącznie warstwy poprawności i żaden wynik konwencji nie dociera do użytkownika. Sesja edytora nie mówi nic o tym, czy encja nadaje się do publikacji, dopóki nie poprosi się o tę warstwę.

Na tej warstwie trzy rzeczy obowiązują niezależnie od wartości klucza. Działa tylko tryb odczytujący lokalną treść, więc żaden rejestr nie jest odpytywany, nic nie jest pobierane i nic nie jest zapisywane; porównanie przed publikacją uzyskuje się, wysyłając aggrega/lint z prePublish, nigdy przez walidację, ponieważ kontrola uruchamiana przy każdej edycji to dokładnie miejsce, w którym nie wolno sięgać do rejestru. Reguły są oceniane względem bufora przesłanego w żądaniu, a nie pliku na dysku, więc poprawiona nazwa przestaje być zgłaszana przed zapisaniem. Wyniki są też doradcze — dokument, który je wywołuje, nadal przechodzi walidację, a jego Release nadal się rozwiązuje i renderuje — więc dodaje to warstwę, a nigdy odmowę.

Klucz steruje tą warstwą i niczym więcej. aggrega/lint odpowiada na wszystko, o co zostanie zapytany, przy dowolnej wartości, ponieważ wywołujący, który go wysyła, poprosił o kontrolę z nazwy.

Sprawdzane są tylko rodzaje publikowane w katalogu, ponieważ tego dotyczą konwencje. Dokumenty, które nie są treścią katalogu — wśród nich Aggregate i Release — są pomijane, podobnie jak YAML, który w ogóle nie jest dokumentem Aggrega. Dzięki temu sesja milczy o dokumentach, w których autor spędza większość czasu.

Jak zapisywana jest zgłaszana ścieżka

Gdy odpowiedź wskazuje dokument, który demon zlokalizował za klienta, o zapisie tej ścieżki decyduje jedna reguła: względnie wobec katalogu głównego obszaru roboczego, gdy dokument leży w jego obrębie, i jako ścieżka bezwzględna, gdy leży poza nim. Obejmuje to file w tożsamości encji, file w definicji encji oraz file, według którego kluczowana jest każda grupa w odpowiedzi lint. Oba zapisy są ścieżkami, które można otworzyć — pierwszy względem wskazanego katalogu głównego, drugi bezpośrednio — i żaden nigdy nie pozostaje pusty z powodu położenia dokumentu.

Druga połowa reguły odpowiada na potrzeby skonfigurowanego katalogu z katalogiem encji. Obszar roboczy może wskazywać katalogi katalogu encji w dowolnym miejscu na maszynie, a dokument w jednym z nich jest równie rzeczywisty jak dokument pod katalogiem głównym. Nazywa go ścieżka bezwzględna i jest to ten sam zapis, który aggrega lint i diagnostyka zatrzymująca drukują dla tego pliku w terminalu — dzięki temu jeden plik ma jedną nazwę bez względu na to, którą powierzchnię się zapytało. Nigdy nie zostanie natomiast podana ścieżka wychodząca ponad katalog główny, która wskazywałaby różne pliki zależnie od miejsca, z którego zostałaby odczytana.

To, który zapis został przekazany, można odczytać z wartości: wszystko, co dana platforma odczytuje jako ścieżkę bezwzględną, jest drugą postacią, a wszystko inne jest względne wobec katalogu głównego obszaru roboczego. Nie trzeba tego sprawdzać, aby otworzyć plik — dołączenie ścieżki względnej do katalogu głównego i otwarcie bezwzględnej bezpośrednio działają w obu przypadkach — ale klient grupujący według dokumentów obszaru roboczego może odróżnić obie postacie bez pytania.

Czego ta reguła nie obejmuje. Ścieżka wysyłana podlega kontraktowi własnemu danego żądania, opisanemu przy tym żądaniu powyżej i zwykle surowszemu: miejsce docelowe jest odrzucane, chyba że jest względne wobec katalogu głównego obszaru roboczego i rozwiązuje się w jego obrębie, łącznie z dowiązaniami. Powiadomienie aggrega/publishDiagnostics zawsze przekazuje swoje file jako ścieżkę bezwzględną, w obrębie katalogu głównego i poza nim, ponieważ ta wartość jest identyfikatorem dopasowywanym do własnych otwartych dokumentów, a nie współrzędną w obszarze roboczym — edytor rozwiązuje ją jako ścieżkę systemu plików. aggrega/releaseCandidates i aggrega/activeRelease wskazują każdą encję Release i każdy plik blokady ścieżką bezwzględną, jak podają ich własne opisy powyżej. Natomiast aggrega/irGraph przekazuje skompilowany graf tak, jak zapisał go kompilator — ukrywając jedynie wartości, które autor zadeklarował jako wrażliwe — więc każda ścieżka w nim zapisana jest tą, którą zapisał kompilator, w postaci ustalonej przez kontrakt samego grafu, a nie ścieżką złożoną przez ten protokół.

Jakie zapisy akceptuje wysyłany parametr

O tym, jakie zapisy akceptuje parametr, decyduje to, co wskazuje ścieżka — a nie to, która metoda ją przenosi. Opis każdego żądania powyżej określa kontrakt dla przyjmowanych przez nie parametrów; poniżej przedstawiono różnicę między nimi i wyjaśniono, dlaczego jest to różnica, a nie niespójność, którą trzeba zapamiętywać dla każdej metody osobno.

Parametr wskazujący dokument, który klient już posiada, można zapisać na jeden z trzech sposobów: względnie wobec katalogu głównego obszaru roboczego, bezwzględnie lub jako adres file://, który klient serwera językowego wysyła dla otwartego dokumentu. Dotyczy to file lub uri w aggrega/validate, aggrega/diagnostics, aggrega/invalidate, aggrega/hover, aggrega/completion, aggrega/resolve, aggrega/findReferences, aggrega/findImplementations, aggrega/insertionPoint i aggrega/connectionAtPosition. Wszystkie trzy wskazują jeden dokument i otrzymują taką samą odpowiedź, ponieważ każdy jest sprowadzany do jednego kanonicznego zapisu na granicy żądania, zanim cokolwiek go odczyta — dokument zwalidowany pod swoją ścieżką zostanie więc znaleziony pod swoim adresem i odwrotnie, a wybór zapisu niczego w odpowiedzi nie zmienia. Adres jest odczytywany jako wskazywana przez niego ścieżka, z zdekodowanymi sekwencjami procentowymi, gdy jego część authority jest pusta lub równa localhost; adres wskazujący inną maszynę jest odczytywany jako udział sieciowy tej maszyny w systemie, który w ten sposób otwiera tam dokument, a gdzie indziej nie wskazuje niczego, co demon mógłby otworzyć. Adres, który zawiera ponadto zapytanie, fragment, dane uwierzytelniające lub port, również nie wskazuje niczego, co demon mógłby otworzyć. Wartość, która nie zaczyna się od file://, bez względu na wielkość liter, nigdy nie jest odczytywana jako adres, a odmowa z powodu niezwalidowanego pliku podaje wysłaną wartość, niezależnie od zapisu. Spośród nich aggrega/insertionPoint i aggrega/connectionAtPosition to dwa żądania, które odczytują dokument z dysku, gdy klient nie ma jego kopii, i odpowiadają tylko dla dokumentu w obrębie obszaru roboczego: dokument poza katalogiem głównym — w zapisanej postaci lub poprzez dowiązanie wyprowadzające poza niego, do pliku lub do katalogu po drodze — jest odrzucany bez względu na to, który z trzech zapisów go wskazuje, a dokument w obrębie katalogu głównego otrzymuje odpowiedź we wszystkich trzech. Pozostałe osiem nie odczytuje niczego z dysku pod wskazaną ścieżką — aggrega/validate pobiera bajty dokumentu z content, a reszta odpowiada na podstawie tego, co zostało zwalidowane — więc odpowiadają dla dokumentu bez względu na to, gdzie klient go przechowuje, w obszarze roboczym lub poza nim, i żadne wskazane przez nie dowiązanie nie jest podążane w celu odczytania pliku. Parametr wskazujący dokument wybrany spoza obszaru roboczego to ten sam przypadek z tego samego powodu: source w aggrega/import jest odczytywany tam, gdzie faktycznie się znajduje, jak podaje jego własny opis. Oba są wyjątkami od granicy obszaru roboczego z racji swojej klasy — dokument, który klient trzyma otwarty, i plik wybrany przez człowieka — a Granica obszaru roboczego wyjaśnia, dlaczego każdy z nich jest wyjątkiem.

Parametr, za pomocą którego demon musi zlokalizować dokument w obrębie obszaru roboczego, przyjmuje ścieżkę względną wobec obszaru roboczego i nic innego. Najważniejszy jest tu release — w aggrega/irGraph i na tym samym kontrakcie wszędzie, gdzie się pojawia — a wartość bezwzględna jest odrzucana z błędem invalid-params, który podaje kontrakt, a następnie wskazuje konkretny błąd. Żądania zapisujące w obrębie obszaru roboczego stosują ten sam kontrakt do swoich miejsc docelowych, jak podaje opis każdego z nich. Każda taka ścieżka jest następnie oceniana według tego, dokąd prowadzi, według jednej reguły bez względu na to, czy żądanie ją odczytuje, czy zapisuje — według definicji „w obrębie” podanej w Granica obszaru roboczego — a ścieżka wyprowadzająca na zewnątrz jest odrzucana z błędem własnym danego żądania, cytującym wartość w wysłanej postaci, bez odczytania ani zapisania czegokolwiek: dotyczy to zarówno dowiązania do pliku na zewnątrz, jak i dowiązania do katalogu po drodze, a także jeszcze nieutworzonej ścieżki pod dowiązanym katalogiem wyprowadzającym na zewnątrz, która jest odrzucana z powodu dowiązania, zamiast zostać zapisana albo wyszukana na zewnątrz i zgłoszona jako brakująca. Obejmuje to każdą ścieżkę, którą żądanie wskazuje demonowi do odczytu — release wszędzie, gdzie się pojawia, entity w aggrega/lint oraz entity, plugin, file i from w żądaniach publikacji — więc żądanie nie może odczytać przez dowiązanie pliku, którego własne listingi obszaru roboczego nie obejmują, a także każde miejsce docelowe: katalogi, do których zapisują generowanie, import i kompilacja, encję, obok której aggrega/pin zapisuje swoją blokadę, plik encji i moduł, które aggrega/pluginSync odczytuje i przepisuje, oraz dokument edytowany przez aggrega/editDocument. Jedynym wyjątkiem jest release wskazujący encję Release, którą wymienia konfiguracja obszaru roboczego, jak podaje opis aggrega/irGraph.

Oba przypadki się różnią, ponieważ różnią się błędy. Parametr wskazujący dokument, który klient już posiada, pozostawia tylko jedno pytanie — który dokument — więc sprowadzenie zapisu do kanonicznego niczego nie traci, a akceptowanie każdego z nich również nic nie kosztuje. Parametr, który wybiera dokument z obszaru roboczego, nie jest w takiej sytuacji: w bibliotekach ścieżek, z których klient prawdopodobnie korzysta, dołączenie wartości bezwzględnej do katalogu głównego daje tę wartość bezwzględną zamiast błędu. Wartość po cichu naprawiona sprawiłaby więc, że demon odczytałby — i zgłosiłby wyniki dla — ścieżkę, której obszar roboczy nigdy nie zawierał, a klient otrzymałby informacje o pliku, który nie istnieje. Odpowiedzią jest odmowa, a nie naprawa, ponieważ demon naprawiający taką wartość utwierdzałby każdego klienta, który ją wysyła, w przekonaniu, że kontrakt jest opcjonalny.

Jak adresowana jest encja

Każda encja wskazana w odpowiedzi jest adresowana w ten sam sposób: kind, name i file. Aby cokolwiek wyświetlić, należy złączyć te trzy klucze z aggrega/catalogIndex: to ta powierzchnia przenosi pełny zestaw opisowy encji — apiVersion, description i labels — dlatego odpowiedź, która musi encję jedynie wskazać, podaje trzy klucze adresujące, a opis pozostawia jednemu miejscu. Wyszukiwanie po nazwie, takie jak aggrega/entityDefinition, powtarza kilka pól opisowych, których dotyczy jego własna odpowiedź; indeks pozostaje powierzchnią, z którą należy łączyć, gdy potrzebny jest cały zestaw.

Tam, gdzie odpowiedź może wskazywać encje z więcej niż jednego miejsca, każda tożsamość przenosi obok tych trzech kluczy origin. Robią tak zarówno aggrega/catalogIndex, jak i aggrega/attachCandidates, ponieważ ich encje pochodzą z dokumentów obszaru roboczego i ze skonfigurowanych katalogów. Odpowiedź czerpiąca tylko z jednego miejsca podaje trzy klucze bez origin, ponieważ klucz o jednej możliwej wartości nic nie mówi — każda encja wskazana w takiej odpowiedzi jest dokumentem obszaru roboczego, a jej file jest ścieżką względną wobec obszaru roboczego, którą można otworzyć. Należy więc odczytywać origin tam, gdzie występuje, zamiast wymagać go wszędzie; w obu przypadkach łączy się po trzech kluczach.

origin należy do odpowiedzi, która wylicza encje, gdzie rozróżnienie populacji jest problemem czytelnika. Odpowiedź po nazwie, taka jak aggrega/entityDefinition, go nie zawiera: wskazuje jedną encję, do której rozwiązała się nazwa, więc nie ma populacji do rozdzielenia. Jej własny punkt powyżej mówi, kiedy jej file jest puste; tej pustki nie należy interpretować przez wartości origin poniżej, które opisują listę.

origin mówi, skąd demon odczytał encję, i to dzięki niemu file daje się odczytać.

  • workspace — dokument Aggrega w katalogu głównym obszaru roboczego. file to jego ścieżka względna wobec tego katalogu, którą klient może otworzyć.
  • catalog — encja rozwiązana ze skonfigurowanych katalogów. Na tej liście file jest puste, a name stanowi cały adres. Jest puste, ponieważ lista podaje to, co wyliczyło wyszukiwanie w katalogu, czyli tożsamość, a nie dokument, więc wpis nie ma ścieżki do podania — nie jest to ścieżka zatajona ze względu na swoje położenie. Aby uzyskać dokument, należy zapytać aggrega/entityDefinition o tę samą nazwę: to żądanie rozwiązuje encję i podaje jej file zgodnie z regułą powyżej, więc katalog spoza katalogu głównego obszaru roboczego jest tam wskazany ścieżką bezwzględną. name i tak jest współrzędną, której używają encja Aggregate, encja Recipe i wyszukiwanie w katalogu.

Oba pola należy czytać razem, zamiast sprawdzać samo file. Puste file samo w sobie nie pozwala stwierdzić, czy encja nie ma ścieżki w obszarze roboczym, czy też ścieżka po prostu nie została podana; origin odpowiada na to bezpośrednio.

Gdy encja Feature jest osiągalna na oba sposoby — katalog główny obszaru roboczego sam jest jednym ze skonfigurowanych katalogów, co jest częstym układem — jest zgłaszana raz, jako dokument obszaru roboczego, ponieważ to jest kopia, której plik można otworzyć.

Co mówi odpowiedź z kandydatami do dołączenia

aggrega/attachCandidates odpowiada na jedno pytanie — które encje Features dopuszcza ten zestaw etykiet — i oferuje trzy sposoby wskazania, o który zestaw etykiet chodzi. Należy wysłać dokładnie jedną współrzędną; wysłanie dwóch lub żadnej jest odrzucane, a nie szeregowane.

{node} adresuje dokument obszaru roboczego przez jego metadata.name i nie potrzebuje niczego więcej. Dopasowanie jest obliczane względem etykiet, które ten dokument deklaruje w metadata.labels, a odpowiedź zgłasza labelSource: "declared".

{graphNode, release} adresuje węzeł skompilowanego grafu. graphNode to identyfikator, pod którym graf przechowuje węzeł — ten sam, który odczytuje się z aggrega/irGraph, łącznie z formą kwalifikowaną, jaką ma węzeł wniesiony przez podagregat. release to ścieżka względna wobec katalogu głównego obszaru roboczego, wskazująca encję Release, której graf ma zostać zbudowany — ta sama wartość, którą przyjmuje aggrega/irGraph. Dopasowanie jest obliczane względem ostatecznych etykiet węzła, a odpowiedź zgłasza labelSource: "resolved".

{labels} niesie sam zestaw etykiet i niczego nie adresuje. To kształt leżący u podstaw dwóch pozostałych: dopasowanie jest funkcją zestawu etykiet i dostępnych encji Features, więc klient, który już ma zestaw etykiet, nie musi niczego nazywać ani na nic czekać. Należy wysłać obiekt JSON z parami etykiet; odpowiedź zgłasza labelSource: "supplied" i puste node, ponieważ to żądanie niczego nie adresowało. Pusty obiekt jest współrzędną — pyta o węzeł bez etykiet — natomiast całkowite pominięcie klucza lub wysłanie null niczego nie adresuje i jest odrzucane.

Dwie współrzędne nazw są oddzielne, ponieważ ich przestrzenie identyfikatorów się nakładają. Identyfikator węzła grafu i metadata.name dokumentu mogą być tym samym ciągiem, a nazywać różne rzeczy, więc jeden parametr niosący oba byłby niejednoznaczny, a demon zgadujący, o którą przestrzeń chodzi, czasem odpowiadałby pewnie w sprawie niewłaściwego obiektu. Niejednoznaczność usuwa wskazanie, jakie pytanie jest zadawane.

labelSource mówi, jak daleko sięga odpowiedź, a trzech wartości nie można stosować zamiennie. declared to dopasowanie względem tego, co jeden dokument mówi o sobie, czyli tego, co widzi odczyt źródła. resolved to dopasowanie względem etykiet, które węzeł faktycznie otrzymuje, czyli tych, względem których kompilacja ocenia możliwość zastosowania — więc odpowiedź resolved jest stwierdzeniem o tym, co rozstrzygnęłaby kompilacja, a odpowiedź declared nie. supplied oznacza, że demon nie odczytał żadnych etykiet i dopasował to, co wysłano; siła tej odpowiedzi zależy całkowicie od tego, skąd pochodzi zestaw etykiet.

Dlatego klient mający graf powinien wysyłać {labels}, a nie nazwę. Ostateczne etykiety węzła to etykiety typu komponentu, do którego węzeł jest rozwiązywany, a nie dokumentu, który przypadkiem ma ten sam identyfikator, a dołączenie label-transform może je następnie uzupełnić, zmienić lub usunąć — więc etykiety decydujące o możliwości zastosowania węzła nie muszą być etykietami deklarowanymi przez jakikolwiek dokument. Klient rysujący graf ma już ten zestaw z aggrega/irGraph; odesłanie go daje tę samą odpowiedź co współrzędna {graphNode, release}, bez ponownego budowania grafu. Jeśli odesłany zostanie zestaw zgłoszony przez sam demon — zestaw węzła z aggrega/irGraph lub encji z aggrega/catalogIndex — wyobrażenie klienta o etykietach węzła nie może rozejść się z wyobrażeniem demona, ponieważ zestaw nigdy nie opuścił jego własnej odpowiedzi. Zestaw złożony samodzielnie jest pytaniem hipotetycznym, na które odpowiedź jest rzetelna, ale nie jest stwierdzeniem o żadnym węźle obszaru roboczego.

Kandydaci pochodzą z obszaru roboczego i z katalogu. Obszar roboczy, który trzyma swoje encje Features w katalogu, a nie we własnym drzewie, nie ma w ogóle lokalnej encji Feature, a wszyscy jego kandydaci mają origin: "catalog". Dla węzła grafu oba źródła są odczytywane w kategoriach encji Release tego węzła: encje Features z katalogu to te, które deklarują katalogi katalogowe przypisane tej encji Release w konfiguracji obszaru roboczego, a własne dokumenty obszaru roboczego są oferowane z pominięciem tych, które leżą w katalogu czytanym wyłącznie przez inne encje Releases. Obszar roboczy, który trzyma wariant encji Feature dla każdej encji Release, oferuje więc grafowi każdej encji Release jej własny wariant i nigdy cudzy, natomiast encja Feature zapisana obok katalogów, poza jakimkolwiek katalogiem katalogowym, jest oferowana dla każdej encji Release. {node} i {labels} nie wskazują żadnej encji Release, więc korzystają ze wszystkich dokumentów obszaru roboczego i z jego własnych catalog_dirs. Encja Feature, która nie deklaruje żadnej możliwości zastosowania, jest kandydatem dla każdego węzła — brak deklaracji nie stawia żadnego wymagania — natomiast taka, której deklaracji nie da się odczytać, nie jest kandydatem dla żadnego, ponieważ traktowanie nieczytelnego selektora jako spełnionego pozwoliłoby literówce poszerzyć ofertę.

Nazwa, której nie da się rozwiązać, jest błędem, a nie pustą listą. Te dwie odpowiedzi znaczą co innego: pusta tablica candidates mówi, że do tego węzła nic nie może zostać dołączone, a zgłoszenie w ten sposób błędnie wpisanej nazwy przedstawiłoby literówkę jako rozstrzygniętą odpowiedź. Odmowa wskazuje przeszukaną przestrzeń, więc wiadomo, czy szukać dokumentu obszaru roboczego, czy węzła grafu. {labels} nie ma takiego ryzyka — nie ma nazwy, którą można źle wpisać — więc zestaw etykiet, którego nic nie dopuszcza, wraca jako udana odpowiedź z pustą tablicą, a żądanie, którego demon nie potrafi odczytać, nadal jest odrzucane przed jakimkolwiek dopasowaniem.

Współrzędna węzła grafu wymaga pliku blokady; dwie pozostałe nie. Zbudowanie grafu oznacza rozwiązanie tego, do czego sięga encja Release, więc ta ścieżka kończy się odmową z błędem braku pliku blokady, gdy żaden nie został wygenerowany, i wskazuje polecenie do uruchomienia — ten sam warunek wstępny, który ma aggrega/irGraph, z tego samego powodu. Adresowanie dokumentu obszaru roboczego nie buduje grafu, a podanie zestawu etykiet nie buduje niczego, więc obie współrzędne działają w obszarze roboczym, którego nikt jeszcze nie przygotował.

Metoda raportuje i nigdy nie tworzy. Niczego nie modyfikuje, niczego nie zapisuje i nie tworzy żadnego dołączenia. Przygotowanie i zastosowanie jakiejkolwiek edycji należy do edytora, w którym znajdują się bufor i historia cofania.

To, co metoda rozwiązuje, zależy od współrzędnej, a te trzy nie są takie same. {node} niczego nie rozwiązuje i nie sięga do żadnego rejestru ani sieci — kandydaci pochodzą z obszaru roboczego i z katalogów katalogowych, które już są na dysku. {labels} rozwiązuje jeszcze mniej: niczego nie wyszukuje, bo nie ma czego wyszukiwać. {graphNode, release} buduje graf encji Release, więc rozwiązuje domknięcie zależności tej encji Release tak samo jak aggrega/irGraph: najpierw z lokalnych katalogów katalogowych i pamięci podręcznej artefaktów, a ze skonfigurowanego rejestru dla encji, której żadne z nich nie zawiera. Wszystkie trzy odpowiadają offline dla obszaru roboczego, którego encje są w całości lokalne; tylko współrzędna węzła grafu może szukać dalej.

Pytanie o połączenie

Połączenie, które rysuje komponent, może mieć własne dołączenia wypełniające sloty, które jego gniazdo deklaruje w konsumującej encji Component — na przykład poświadczenie, które komponent przedstawia temu, do czego połączenie prowadzi. Aby zapytać, co może się tam znaleźć, należy wysłać connection obok {graphNode, release}: socket to gniazdo zależności, przez które połączenie jest poprowadzone, a alias to nazwa, jaką połączenie nosi w tym gnieździe, oba dokładnie tak, jak zapisał je autor. Połączenie istnieje tylko w skompilowanym grafie, dlatego connection obok node lub labels jest odrzucane, podobnie jak połączenie bez gniazda lub bez aliasu albo takie, którego węzeł nie rysuje.

Odpowiedź to odpowiedź dla węzła grafu uzupełniona o sloty połączenia. candidates zachowuje swoje znaczenie — encje Features, które mogą zostać dołączone do samego węzła — a dodawane jest slots, jeden wpis na każdy slot deklarowany przez gniazdo, w kolejności, w jakiej deklaruje je encja Component:

  • slot — nazwa, pod którą dołączenie wypełniające slot jest zapisywane w features połączenia.
  • selector, required, inject, sensitive i description — slot dokładnie tak, jak encja Component deklaruje go w gnieździe; puste lub false tam, gdzie nic nie deklaruje. selector to ograniczenie, którym zawężono kandydatów, więc kandydata lub jego brak można wyjaśnić na podstawie samej odpowiedzi.
  • candidates — encje Features, które mogą wypełnić ten slot w tym połączeniu. Build stosuje do takiego dołączenia dwie reguły i obie są tu uwzględniane: zadeklarowaną stosowalność encji Feature względem sfinalizowanych etykiet węzła, której podlega każde dołączenie węzła, oraz selector slotu względem własnych etykiet encji Feature. Kandydaci slotu zawsze należą więc do kandydatów węzła, zawężonych selektorem. Encja Feature, względem której etykiet selektora nie da się obliczyć, nie jest proponowana, ponieważ build ją odrzuca, a nie dopuszcza.

Gdy żaden slot nie może zostać wypełniony, slots jest pustą listą, a noSlotReason podaje przyczynę. Należy odczytać przyczynę, zamiast traktować pustą listę jako „żadna encja Feature nie pasuje” — to byłaby inna odpowiedź, a właśnie przyczyna pozwala je rozróżnić:

  • feature-created-connection — połączenie narysowała encja Feature, z własnego bloku zależności. Dołączenie zapisuje się tylko w połączeniu rysowanym przez komponent lub encję Release, więc nic tu nie trafia, niezależnie od tego, co deklaruje gniazdo.
  • ad-hoc-socket — gniazdo nie jest deklarowane przez encję Component. Autor je nazwał, co jest dozwolone, a niezadeklarowane gniazdo nie deklaruje żadnego slotu.
  • no-slot-declared — encja Component deklaruje gniazdo bez żadnego slotu.

noSlotReason nie występuje tam, gdzie slot istnieje, a slots i noSlotReason nie występują w odpowiedzi na żądanie, które nie wskazuje połączenia — dzięki temu żądanie bez połączenia otrzymuje odpowiedź bez żadnego z tych pól.

document jest akceptowane i niczego tu nie zmienia. Sloty należą do gniazda, a kandydaci do encji Features, niezależnie od dokumentu, w którym dołączenie jest zapisane; to, gdzie trafia, jest odpowiedzią aggrega/attachmentContainer. Wartość inna niż aggregate lub release jest nadal odrzucana, ponieważ wartość przyjęta i zignorowana wygląda dla nadawcy jak uwzględniona.

Co mówi odpowiedź z kandydatami połączeń

aggrega/connectionCandidates odpowiada jednocześnie na dwa pytania, a pełną odpowiedź ma tylko jedno z nich. Odczytanie odpowiedzi jako jednej przefiltrowanej listy prowadzi do błędnej odpowiedzi na drugie.

Każde zgłoszone gniazdo zawiera targets — lokalne dla obszaru roboczego encje Components, których zadeklarowane etykiety spełniają ograniczenie etykiet deklarowane przez to gniazdo wobec tego, co może je spełnić — oraz selector, na podstawie którego obliczono te cele, flagę required deklarowaną przez gniazdo i declaration. targets jest zawsze tablicą, pustą, a nie nieobecną, więc gniazdo, którego nic nie spełnia, nadal jest zgłaszane jako gniazdo deklarowane przez encję.

Część dotycząca celów jest kompletna. Zbiór ustala się, oceniając zadeklarowane ograniczenie gniazda względem zadeklarowanych etykiet kandydata — tak samo, jak robi to kompilacja — więc to, co się proponuje, jest tym, co to samo ograniczenie dopuszcza podczas kompilacji. Gniazdo, które nie deklaruje ograniczenia, pozostawia swoje cele nieograniczone i zgłasza każdą encję Component — tak język ograniczeń rozumie pusty selektor; nie jest to błąd.

Część dotycząca gniazd jest otwarta, a declaration wraz z adHocSocketsAccepted pozwalają to rozpoznać. Autor encji Aggregate odpowiada za jej topologię i może podłączyć gniazdo, którego encja katalogowa komponentu nigdy nie zadeklarowała, więc gniazda deklarowane przez encję są pomocnym zbiorem początkowym, a nie zbiorem dozwolonych nazw gniazd. Należy je przedstawiać jako sugestie, a nie jako jedyne możliwości — selektor oferujący tylko zadeklarowane gniazda sugerowałby autorowi, że jego swoboda jest węższa, niż jest w rzeczywistości.

  • declaration ma wartość declared, gdy adresowana encja wymienia gniazdo w swoim usesSchema, oraz ad-hoc, gdy go nie wymienia. Są to te same dwie wartości, które niesie krawędź w grafie IR, więc jedno słownictwo odpowiada na pytanie „skąd pochodzi to gniazdo” wszędzie, gdzie się ono pojawia.
  • adHocSocketsAccepted informuje, czy powierzchnia adresowanej encji akceptuje gniazdo, którego nie wymienia jej własna deklaracja. Nie zawsze ma wartość prawda: własna powierzchnia zależności encji Component je akceptuje, a powierzchnia dołączeń encji Feature nie, ponieważ dołączenie uczestniczy w topologii deklarowanej przez dołączoną encję Feature, zamiast tworzyć własną. Gniazdo ad hoc na powierzchni, która go nie akceptuje, jest zgłaszane bez celów, ponieważ żadne połączenie przez nie nie dałoby się zbudować.

Podanie socket w żądaniu zawęża odpowiedź do tego jednego gniazda i jest to jedyny sposób, aby zapytać o gniazdo, którego encja nie deklaruje — niezadeklarowane gniazdo nie występuje w żadnej deklaracji, którą można by wyliczyć. Po pominięciu go otrzymuje się każde gniazdo deklarowane przez encję, w kolejności, w jakiej zostały zapisane.

Zgłaszane jest dopasowanie względem zadeklarowanych etykiet. Kompilacja ocenia ograniczenie gniazda względem sfinalizowanych etykiet węzła na drugim końcu krawędzi, a są to etykiety typu komponentu, do którego węzeł jest rozwiązywany, po zadziałaniu wszelkich dołączeń label-transform — niekoniecznie etykiety wskazanego dokumentu. Pozytywna odpowiedź nie jest więc obietnicą tego, co postanowi kompilacja — to to samo ograniczenie, które aggrega/attachCandidates ma przy źródle etykiet declared.

Metoda zgłasza i nigdy nie tworzy. Niczego nie rozwiązuje, nie łączy się z żadnym rejestrem ani siecią i niczego nie zapisuje: nie tworzy krawędzi i nie proponuje tekstu. Przygotowanie i zastosowanie edycji należy do edytora, w którym znajdują się bufor i historia cofania.

Dla tożsamości encji w targets — kind, name i file — należy wykonać złączenie z aggrega/catalogIndex w sposób opisany w sekcji Jak adresowana jest encja. Pola opisowe są zgłaszane tam i celowo nie są tu powtarzane, więc ta odpowiedź nie zawiera ich drugiej kopii, która mogłaby się rozsynchronizować. Cele są encjami Components obszaru roboczego, więc każdy ma file, który można otworzyć, i żaden nie ma origin: ta odpowiedź korzysta z jednego miejsca, a złączenie odbywa się po trzech kluczach.

Co mówi odpowiedź attachment-container

aggrega/attachmentContainer znajduje się między opisanymi wyżej żądaniami kandydatów a opisanym niżej punktem wstawienia. Tamte mówią, co może zostać dołączone do węzła; to mówi, do którego kontenera należy dołączenie dla niego i w którym dokumencie; następne mówi, w którym miejscu bajtów tego dokumentu trafia tekst.

Należy pytać o kontener, a nie składać go samodzielnie. Identyfikator węzła i ścieżka podsystemu, który go zawiera, są zapisywane z kropkami między częściami, a kropka jest dozwolonym znakiem w nazwie wpisywanej przez autora — dlatego spoza dokumentu nie da się odróżnić kropki strukturalnej od kropki wewnątrz nazwy. Klient, który złożyłby ścieżkę sam, otrzymałby coś, co wygląda poprawnie, a wskazuje klucz, którego nikt nie zapisał, i następująca po tym edycja utworzyłaby ten klucz, zamiast zostać odrzucona. Obie ścieżki złożył kompilator, więc to kompilator je rozkłada.

Identyfikator węzła nie zawiera żadnego śladu podsystemu, który go otacza. Komponent zapisany wewnątrz subsystems.billing.subsystems.payments ma w grafie klucz ledger, dokładnie tak jak komponent najwyższego poziomu, więc w identyfikatorze nie ma niczego, na czym klient mógłby się oprzeć, jakkolwiek starannie by go dzielił.

Odpowiedź składa się z trzech pól.

  • node powtarza węzeł, którego dotyczy odpowiedź, dzięki czemu klient z kilkoma oczekującymi żądaniami może dopasować każdą odpowiedź do pytania bez prowadzenia własnej kolejności.
  • file to dokument, w którym zapisano węzeł, ze ścieżką względną wobec przestrzeni roboczej. Jest częścią odpowiedzi, a nie czymś już znanym: węzeł wniesiony przez importowany moduł został zapisany we własnym dokumencie tego modułu pod nazwą nadaną przez moduł, więc zarówno plik, jak i ostatni segment kontenera różnią się od wszystkiego, co podano w żądaniu.
  • container to ścieżka strukturalna od korzenia tego dokumentu w postaci listy segmentów — ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Każdy poziom otaczającego podsystemu znajduje się ponownie pod kluczem subsystems, bo tak zapisuje to dokument. Komponent zapisany przez autora na najwyższym poziomie wskazuje zamiast tego ["spec", "components", "checkout", "features"], ponieważ zakres, do którego taki komponent jest kompilowany, nie jest zawarty w żadnym pliku.

Jest to lista segmentów, a nigdy połączony ciąg znaków, i właśnie o to chodzi w tym kształcie. Połączoną ścieżkę odbiorca musiałby ponownie podzielić, co przywróciłoby opisaną wyżej niejednoznaczność jedno wywołanie później. Listę należy przekazać bez zmian do aggrega/insertionPoint jako jego container.

Odczytuje strukturę, a nigdy znaczenie. Odpowiedź wynika z dokumentu, w którym zapisano węzeł, z zakresu, w którym się znajduje, i z nazwy wpisanej przez autora. Nic nie jest odczytywane z tego, jak nazywa się komponent, jaki ma typ ani co mówi jakakolwiek etykieta.

Raportuje i nigdy nie zapisuje. Metoda niczego nie modyfikuje i nie zapisuje niczego w żadnym dokumencie. Nie tworzy dołączenia, nie składa tekstu i nie stosuje edycji; nie rozstrzyga też, co może zostać dołączone — tym zajmuje się aggrega/attachCandidates.

Żądanie wskazujące węzeł, którego graf nie zawiera, jest odrzucane, a nie obsługiwane. Identyfikatory węzłów są własnymi kluczami grafu — należy je odczytywać z grafu zwracanego przez aggrega/irGraph — a węzeł wniesiony przez importowany moduł ma identyfikator kwalifikowany. Odrzucany jest także węzeł, dla którego graf nie rejestruje dokumentu: miejsce dołączenia jest faktem dotyczącym dokumentu, więc węzeł bez dokumentu nie ma odpowiedzi, a nie ma odpowiedź pustą.

Wymaga pliku lockfile z tego samego powodu co aggrega/irGraph: wskazanie kontenera oznacza zbudowanie grafu encji Release, a graf zbudowany z bajtów, za które nic nie ręczy, byłby raportowany dokładnie tak samo jak graf sprawdzony.

Dołączenie na połączeniu

Należy wysłać connection obok {graphNode, release} — jego socket, jego alias i jego document — a odpowiedź wskaże kontener features we własnym wpisie tego połączenia zamiast we wpisie węzła. document jest tu wymagany, ponieważ dołączenie na połączeniu narysowanym przez encję Aggregate może się znajdować w każdym z dokumentów: deweloper zapisuje je we wpisie połączenia w encji Aggregate, operator we wpisie dla danej krawędzi w encji Release.

  • aggregate wskazuje wpis połączenia w dokumencie, w którym zapisano węzeł — ["spec", "components", "gateway", "uses", "models", "gpt", "features"] dla komponentu najwyższego poziomu, z każdym otaczającym podsystemem zapisanym poziom po poziomie, jak wyżej. Połączenie narysowane przez encję Release nie ma wpisu w encji Aggregate, więc jest tam odrzucane.
  • release wskazuje wpis dla krawędzi pod własnym wpisem encji Release dla węzła — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"] — niezależnie od tego, czy encja Release już zapisuje ten wpis dla krawędzi. Jeśli go nie zapisuje, aggrega/insertionPoint raportuje klucze, które trzeba jeszcze zapisać, w missingContainerKeys. file jest wtedy dokumentem encji Release. Encja Release, która nie zapisuje żadnego wpisu dla węzła, jest odrzucana: rozmieszczenie węzła zapisuje operator, a odpowiedź o tym nie rozstrzyga.

Połączenie narysowane przez encję Feature jest odrzucane w obu dokumentach z powodu, który podaje opisany wyżej feature-created-connection. Węzeł, gniazdo i alias są dopasowywane dokładnie tak, jak zostały zapisane, a połączenie, którego węzeł nie rysuje, jest odrzucane, a nie obsługiwane ścieżką. Wszystkie pozostałe opisane wyżej właściwości obowiązują bez zmian: odpowiedź jest listą segmentów, odczytuje strukturę, a nigdy znaczenie, i niczego nie zapisuje.

Co mówi odpowiedź connection-at-position

aggrega/connectionAtPosition to krok poprzedzający dwa opisane wyżej żądania dotyczące połączeń, przeznaczony dla klienta, który zna miejsce w dokumencie, a nie węzeł w grafie — na przykład kursor na wpisie połączenia. Odpowiada, które połączenie jest tam zapisane, we współrzędnych przyjmowanych przez tamte żądania, i na tym poprzestaje.

Odpowiedź to jedna z dwóch połówek, nigdy obie.

  • graphNode i connection — węzeł, którego komponent rysuje połączenie, wskazany identyfikatorem, pod którym klucz nadaje mu skompilowany graf, oraz połączenie wskazane przez socket i alias, przy czym document wskazuje dokument, w którym odczytano pozycję: aggregate dla encji Aggregate lub importowanego przez nią modułu, release dla encji Release. Należy przekazać graphNode, ten sam release i connection do aggrega/attachCandidates, aby uzyskać sloty deklarowane przez gniazdo połączenia, oraz do aggrega/attachmentContainer, aby dowiedzieć się, gdzie trafia dołączenie do niego; wskazany kontener leży wewnątrz tego samego wpisu, w który trafiła pozycja.
  • noConnectionReason — dlaczego nie zgłoszono żadnego połączenia. Zbiór jest zamknięty:
    • no-connection-entry — pozycja nie leży na żadnym wpisie, w którym zapisuje się dołączenie. Połączenie zapisane jako lista celów (db: [store]) oraz połączenie rysowane przez własny blok zależności encji Feature nie mają takiego wpisu, więc pozycja na którymkolwiek z nich również daje tę odpowiedź.
    • feature-created-connection — pozycja leży na wpisie encji Release dla połączenia narysowanego przez Feature, które nie przyjmuje dołączeń z powodu podanego wyżej w odpowiedzi o slotach. Release zapisuje taki wpis, gdy blok zależności encji Feature rysuje połączenie przez gniazdo, które deklaruje również konsumujący Component; wpis się buduje niezależnie od tego, czy niczego nie konfiguruje, czy ustawia infra per krawędź dla połączenia.
    • unknown-connection — pozycja leży na wpisie, który Release zapisuje dla połączenia nieobecnego w skompilowanym grafie. Release, który się buduje, może zawierać taki wpis — na przykład wpis pod aliasem, którego nic nie rysuje, i który niczego nie konfiguruje (brak target, infra i features), albo wpis dla komponentu wyłączonego przełącznikiem active:, którego połączenia wypadają z budowania razem z nim.

Które wpisy się liczą. W encji Aggregate — każde połączenie rysowane przez komponent, w jego wpisie pod aliasem połączenia w dokumencie, w którym komponent został zdefiniowany; dla komponentu dostarczonego przez importowany moduł jest to własny dokument tego modułu. W encji Release — każdy zapisany w niej wpis per krawędź, niezależnie od tego, czy wpis rysuje swoje połączenie, czy konfiguruje połączenie narysowane przez Aggregate. Położenie każdego wpisu jest zapisane w skompilowanym grafie, więc to, czy klucz jest połączeniem, nigdy nie jest wywnioskowane z jego nazwy. Komponent wyłączony przełącznikiem active: nie występuje w skompilowanym grafie, więc jego własne wpisy w Aggregate dają odpowiedź no-connection-entry, a wpis encji Release dla jednego z jego połączeń — unknown-connection.

Pozycja w dowolnym miejscu wpisu leży wewnątrz niego. Wpis rozciąga się od klucza aliasu do ostatniego wiersza wciętego pod nim, więc pozycja na aliasie, na jego target lub wewnątrz jego features otrzymuje odpowiedź dla tego połączenia, a przy zagnieżdżonych wpisach wygrywa najgłębszy. Pozycja na własnym kluczu gniazda, powyżej zapisanych pod nim aliasów, nie leży w żadnym z nich — niezależnie od tego, czy gniazdo ma jeden alias, czy kilka — podobnie jak pozycja we wcięciu przed kluczem aliasu.

To, który dokument jest którym, wynika z encji Release. Własny plik encji Release jest odczytywany pod kątem zapisanych w nim wpisów; każdy inny plik — pod kątem wpisów komponentów, które graf rejestruje jako w nim zdefiniowane. Dokument, z którego graf encji Release niczego nie odczytuje, w każdej pozycji daje odpowiedź no-connection-entry.

Tylko raportuje i nigdy nie zapisuje, a dokument odczytuje tak samo jak aggrega/insertionPoint: najpierw z kopii sesji, a w przeciwnym razie z dysku, wewnątrz obszaru roboczego, z tymi samymi odmowami dla dokumentu spoza niego, nieczytelnego lub niebędącego poprawnie sformułowanym YAML. Wymaga pliku lockfile z tego samego powodu co aggrega/attachmentContainer i buduje graf bez renderowania czegokolwiek.

Co mówi odpowiedź insertion-point

aggrega/insertionPoint jest odpowiednikiem dwóch powyższych żądań o kandydatów. Tamte mówią, co może zostać dołączone lub połączone; to mówi, gdzie w jednym konkretnym dokumencie należy umieścić odpowiedni tekst. Udziela odpowiedzi i na tym poprzestaje.

Kontener wskazuje wywołujący; demon go lokalizuje. container to ścieżka strukturalna od korzenia dokumentu — ["spec", "components", "web", "features"] — i stanowi deklarację wywołującego, gdzie wpis tego rodzaju należy w dokumencie tego rodzaju. Demon nie wyprowadza tej ścieżki z nazwy encji, jej typu ani tego, co zdaje się oznaczać. Odczytuje bajty zapisane przez autora i zgłasza, które segmenty ścieżki dokument już zawiera, w których kolumnach leżą jego wpisy i do której ostatniej linii sięga jego najbardziej wewnętrzny blok. Wiedza, który klucz, pozostaje więc po stronie wywołującego, a wiedza, gdzie w tym pliku trafiają wpisy tego klucza, pochodzi stąd.

W przypadku dołączenia Feature do węzła skompilowanego grafu wywołujący nie musi sam znać tego klucza: można zapytać aggrega/attachmentContainer o dokument i kontener, a następnie przekazać oba tutaj bez zmian.

Odpowiedź to pozycja o zerowej szerokości oraz to, co należy wokół niej zapisać. file to dokument, względem obszaru roboczego. container powtarza ścieżkę, o którą pytano, dzięki czemu klient z kilkoma oczekującymi żądaniami paruje każdą odpowiedź z jej pytaniem bez prowadzenia własnej kolejności. position wstawia, a nie zastępuje: nic, co już jest w dokumencie, nie zostaje nadpisane ani przesunięte.

  • precededByLineBreak — zapisywany tekst należy zacząć od znaku nowej linii. Pozycja leży na końcu linii, po której następuje nowy wpis; jest ona w zakresie niezależnie od tego, czy plik kończy się znakiem nowej linii, i nie narusza żadnego już zapisanego bajtu. Wartość false występuje tylko dla dokumentu, w którym nie ma nic, po czym można by się umieścić; wtedy zapis zaczyna się od początku pliku.
  • missingContainerKeys — segmenty ścieżki kontenera, których dokument jeszcze nie zawiera, od najbardziej zewnętrznego. Każdy z nich należy zapisać jako osobny klucz, zanim wpis będzie mógł trafić do najbardziej wewnętrznego. Lista jest pusta, gdy cała ścieżka już istnieje.
  • entryIndent — kolumna, od której zaczyna się pierwsza linia wpisu, liczona w spacjach od początku linii.
  • indentStep — o ile dalej jest wcięty każdy kolejny poziom zagnieżdżenia.
  • indentStepMeasured — czy ten krok zmierzono na podstawie zagnieżdżenia samego dokumentu. Gdy wartość to false, dokument nie zawiera zagnieżdżenia do zmierzenia, a krok jest wartością zastępczą, więc klient, który wolałby narzucić własny, wie, że może to zrobić.
  • entryShape — mapping lub sequence, odczytane z tego, co kontener już zawiera, oraz unknown, gdy kontenera jeszcze nie ma lub nic nie zawiera. unknown nie oznacza błędu: dokument nie określił kształtu swoich wpisów, więc ten wybór należy do wywołującego.

Zastosowanie. Gdy ustawione jest precededByLineBreak, należy zapisać znak nowej linii. Następnie po jednej linii na każdy wpis missingContainerKeys, od najbardziej zewnętrznego, każda zawierająca klucz i dwukropek — pierwsza wcięta o entryIndent minus indentStep razy liczba brakujących kluczy, a każda następna o indentStep dalej. Następnie sam wpis, wcięty o entryIndent. Gdy missingContainerKeys jest puste, wpis jest jedyną zapisywaną linią.

Należy odczytywać missingContainerKeys nawet wtedy, gdy oczekuje się, że kontener istnieje. Pozycja zastosowana bez kluczy, które muszą ją poprzedzać, daje dokument, który przestaje się parsować — to jedyny błąd, którego ta odpowiedź nie może pozwolić uznać za nieobecny.

position liczy od zera, w odróżnieniu od pozycji diagnostyki. Zarówno line, jak i character są liczone od 0, zgodnie z wartościami pozycji w kształcie LSP, które ten protokół wykorzystuje, natomiast line i column we wpisie diagnostyki są liczone od 1, jak opisano w What a diagnostic entry carries (Co zawiera wpis diagnostyki). Klient zasilający jedną powierzchnię danymi z drugiej dokonuje konwersji między nimi.

positionEncoding określa jednostki, w których mierzone jest character, i jest to kodowanie wynegocjowane podczas uzgadniania połączenia. Jest zgłaszane w odpowiedzi, a nie pozostawione domyślnie, ponieważ pozycji, której jednostek wywołujący musi się domyślać, nie da się zastosować: przesunięcia zmierzone w jeden sposób i zastosowane w buforze mierzonym w inny uszkadzają dokument przy pierwszym znaku spoza ASCII.

Żądanie, które nie wskazuje miejsca, w którym może znaleźć się wpis, jest odrzucane, a nie obsługiwane. Każdy z poniższych przypadków jest stanem żądania, a nie obszaru roboczego, więc wraca ze standardowym kodem invalid-params, a ponowienie niczego nie zmienia, dopóki nie zmieni się file lub container.

  • Dokument nie został wskazany, nie leży w obszarze roboczym, nie dało się go odczytać lub nie jest poprawnie sformułowanym YAML — dokument bez struktury nie ma pozycji do zgłoszenia.
  • Ścieżka kontenera niczego nie wskazuje: nie ma segmentów lub jeden z jej segmentów jest pusty.
  • Ścieżka przechodzi przez wartość, którą dokument zawiera jako skalar. Wewnątrz skalara nie można niczego dopisać, a jego zastąpienie byłoby przepisaniem, a nie wstawieniem.
  • Ścieżka dochodzi do kolekcji zapisanej przez autora w stylu flow. Dopisanie do niej wpisu przepisuje bajty już zapisane przez autora zamiast dodać linię, co jest edycją, a nie pozycją.
  • Ścieżka adresuje sekwencję blokową czymś, co nie jest jednym z jej indeksów. Wpisy sekwencji są adresowane pozycją, więc nazwa niczego w niej nie wskazuje i nie można utworzyć wpisu o tej nazwie.

Odczytywany jest bufor przechowywany przez edytor, a nie tylko plik na dysku. Najpierw sprawdzana jest pamięć podręczna parsowania demona, więc pozycja jest zgłaszana względem niezapisanej treści, jeśli taka istnieje, a względem samego pliku, gdy pamięć podręczna nic dla niego nie zawiera.

Metoda tylko raportuje i nigdy nie zapisuje. Niczego nie modyfikuje, niczego nie rozwiązuje, nie łączy się z żadnym rejestrem ani siecią i niczego nie zapisuje w żadnym dokumencie. Nie komponuje tekstu wpisu ani go nie stosuje. Komponowanie i stosowanie edycji należy do edytora, w którym znajdują się bufor i historia cofania.

Co mówi odpowiedź na edycję dokumentu

aggrega/editDocument to druga połowa powyższej pary: tamte żądania mówią, gdzie należy wpis, i zostawiają jego złożenie i zastosowanie klientowi; to żądanie składa i stosuje jeden wpis, i zapisuje. Obie pozostają dostępne, ponieważ klient z niezapisanym buforem i klient edytujący to, co jest na dysku, potrzebują różnych połówek — edytor z własną historią cofania sam umieszcza tekst, a klient, który woli, by plik został zedytowany, niż dowiedzieć się, gdzie go edytować, wysyła to żądanie.

Jedno wywołanie stosuje jedną edycję, a zbiór edycji jest zamknięty. edit określa, którą: add-component dodaje instancję komponentu w kontenerze komponentów, attach-feature dołącza Feature do węzła, wire-edge tworzy połączenie w jednym z gniazd zależności węzła, a set-value ustawia jedną wartość na węźle. Nie ma edycji, która usuwa, zastępuje już napisany blok, zmienia kolejność czegokolwiek lub zapisuje dosłownie dostarczone bajty — nie jest to więc narzędzie do zapisu plików pod węższą nazwą, a wartość spoza tych czterech jest odrzucana, a nie interpretowana. Odmowa wymienia, co można podać.

Węzeł podaje się jako ścieżkę strukturalną, dokładnie tak, jak przyjmują ją dwa powyższe żądania. node to ścieżka od korzenia dokumentu — ["spec", "components", "web"] — a kontener, do którego trafia wpis, wynika z edit. Dla add-component ścieżka wskazuje sam kontener komponentów, ponieważ dodawany wpis jest węzłem. name to klucz, pod którym zapisywany jest wpis: nazwa instancji, nazwa dołączenia, alias połączenia lub klucz wartości. value to zawartość wpisu, a jej znaczenie wynika z edit — encja, której wpis żąda, węzeł, na który wskazuje połączenie, lub skalar, na który ustawiana jest wartość. socket jest odczytywane dla wire-edge i ignorowane w pozostałych przypadkach.

Ścieżka zamiast nazwy — z tego samego powodu, z którego przyjmuje ją żądanie lokalizujące: nazwy trzeba by szukać, a nazwa występująca na dwóch poziomach zostawiłaby kompilatorowi decyzję, o którą chodziło. Klient, który wie, jaki węzeł edytuje, mówi to więc wprost, a klient, który nie wie, wie, że przed edycją musi odpowiedzieć na pytanie.

Każdy bajt, którego edycja nie dotyka, zostaje zachowany. Dokument jest parsowany tylko w celu zlokalizowania kontenera i wiersza, na którym kończy się jego blok; wpis jest renderowany i wstawiany na poziomie wierszy. Komentarze, puste wiersze, styl cytowania, skalary złożone i dosłowne, wyrażenia szablonów oraz kształt końcowego znaku nowego wiersza przechodzą bez zmian, a krok zagnieżdżenia jest mierzony na podstawie wcięć samego dokumentu, a nie narzucany — wpis trafia więc w stylu, w którym już się pisze. To samo żądanie wobec tego samego dokumentu daje te same bajty, więc klient może porównać dwa przebiegi, a w przeglądzie jedna edycja to jeden diff.

Wynik musi być dokumentem, który można by wpisać ręcznie, i od tego zależy zapis. Złożony dokument jest walidowany względem schematu własnego rodzaju i trafia na dysk tylko wtedy, gdy walidacja przejdzie. Żądanie, które dałoby coś odrzucanego przez schemat autorski, wraca jako E0275 — edycja została odrzucona, ponieważ wynikowy dokument nie byłby poprawny, i nic nie zostało zapisane — wraz z właściwością, której schemat nie dopuścił, i jej miejscem. Plik pozostaje bajt w bajt taki, jaki był, więc odrzucona edycja jest nieodróżnialna od niepodjętej i można ponowić poprawione żądanie wobec dokumentu wyjściowego. Dlatego też nie powtarza się tu żadnej reguły: żądanie, by dokument Release zawierał wartość deweloperską, jest odrzucane przez ten sam schemat, który odrzuciłby dokument wpisany ręcznie.

To, co jest dopuszczalne semantycznie, nie jest tu rozstrzygane. Czy gniazdo zależności jest zadeklarowane przez producenta lub czy spełniono warunki stosowalności Feature, należy do rozwiązywania wykonywanego przez build, z własnym raportowaniem. Można więc podać połączenie, o którym to żądanie nigdy nie słyszało, a encja Aggregate może definiować gniazdo, którego jej encja katalogowa nie deklaruje z góry; to, co może być konsumowane przez gniazdo, nadal deklaruje producent. Gdy o to chodzi, należy uruchomić aggrega/validate ze wskazaniem Release lub zażądać grafu.

Odpowiedź mówi, co zostało wstawione i co trafiło na dysk — to różne pytania. content zawiera dokument wytworzony przez edycję w obu trybach dostarczenia. written wskazuje plik, który trafił na dysk, i jest puste przy dryRun. container to ścieżka strukturalna kontenera, w którym znalazł się wpis, dzięki czemu można zlokalizować to, co właśnie dodano, bez ponownego wyprowadzania tej reguły. createdContainers wymienia segmenty zapisane przez tę edycję, ponieważ dokument ich nie zawierał, od najbardziej zewnętrznego — puste w zwykłym przypadku, gdy cała ścieżka już istniała; jego odczyt pozwala odróżnić wpis dodany w istniejącym bloku od takiego, który utworzył własny blok. file i edit powtarzają to, co wysłano, więc klient z kilkoma oczekującymi żądaniami dopasowuje każdą odpowiedź do pytania. written, container i createdContainers są zawsze tablicami, pustymi zamiast nieobecnych.

Przy dryRun nic nie jest tworzone. written jest puste, content zawiera dokument, który wytworzyłby zapis, a plik pozostaje nietknięty — edytor może więc pokazać wynik autorowi do zapisania, poprawienia lub odrzucenia. Domyślnie następuje zapis, ponieważ produktem operacji jest zedytowany dokument, a interfejs, który go wytwarza, jest go winien: żądanie, które nic nie mówi o sposobie dostarczenia, edytuje plik.

Wszystko inne, co robi zapis, robi też przebieg próbny. Złożony dokument jest w obu przypadkach walidowany względem schematu własnego rodzaju, więc edycja odrzucona przy zapisie jest odrzucana również przy dryRun, ze wskazaniem tej samej właściwości — co oznacza, że błąd z przebiegu próbnego jest tym błędem, który dałby zapis.

Wpis, który już istnieje i zawiera to, o co proszono, nie powoduje żadnej operacji — dokument wraca bez zmian i nic nie jest zapisywane. Wpis o tej nazwie zawierający coś innego jest odrzucany, a nie zastępowany, ponieważ zastąpienie tego, co napisał autor, nie jest jedną z czterech edycji.

Po zapisie demon ponownie odczytuje dokument. To, co przechowywał dla tego pliku, jest odrzucane, a jego widok na poziomie przestrzeni roboczej resetowany, więc następne żądanie walidacji, podpowiedzi, uzupełniania lub grafu jest obsługiwane na podstawie bajtów wytworzonych przez edycję, a nie zastąpionej wersji. Sama edycja odczytuje plik z dysku, a nie przechowywany bufor — w przeciwieństwie do powyższego żądania lokalizującego, które najpierw sprawdza niezapisaną treść. To celowe: zapis z niezapisanego bufora umieściłby treść, której autor nie zapisał, pod pozorem zastosowania jednego wpisu. Należy zapisać bufor, a potem edytować.

Żądanie, które nie wskazuje miejsca, w którym może się znaleźć wpis, jest odrzucane, a nie obsługiwane, ze standardowym kodem invalid-params, a ponowienie nic nie zmienia, dopóki nie zmieni się żądanie. Dokument nie został podany, nie znajduje się w przestrzeni roboczej, nie dał się odczytać, nie jest poprawnym YAML lub nie deklaruje rodzaju, względem którego schematu można sprawdzić wynik; edit nie zostało podane lub nie jest jedną z czterech edycji; node nic nie wskazuje lub jeden z jego segmentów jest pusty; nie podano name; wire-edge nie wskazało socket; set-value otrzymało mapowanie lub sekwencję tam, gdzie należy skalar; ścieżka węzła dociera do skalara lub sekwencji albo do kolekcji zapisanej w stylu flow, gdzie dodanie wiersza przepisałoby bajty już obecne; albo ścieżka węzła nie dociera do niczego w dokumencie.

W żadnym trybie dostarczenia nie rozwiązuje zależności, nie łączy się z rejestrem ani nie korzysta z sieci.

Co obejmuje odpowiedź z efektywną konfiguracją

aggrega/effectiveConfiguration odpowiada na dwa pytania: jaka konfiguracja obowiązuje w tej sesji i która warstwa zdecydowała o każdym ustawieniu. Jest to ta sama odpowiedź, którą wypisuje aggrega config show --origin, obliczana raz i zgłaszana na obu powierzchniach, więc obie nie mogą się różnić co do pochodzenia ustawienia.

Wartość source ma jedną z czterech postaci. Ścieżka bezwzględna pliku konfiguracyjnego — łącznie z plikiem globalnym, który odczytuje demon uruchomiony jako aggrega --config <file> serve, podanym jako ścieżka, którą otrzymał; zmienna środowiskowa poprzedzona prefiksem env:, na przykład env:AGGREGA_SIGNING_REQUIRED; flaga globalna wpisana w wierszu poleceń, który uruchomił demona, podana jako flaga, na przykład --offline dla demona uruchomionego jako aggrega --offline serve; albo (built-in defaults) dla ustawienia, którego nie ustawia żadna warstwa. Pierwsze trzy pojawiają się dosłownie w layers. Wartości domyślne nie, ponieważ nie są warstwą, która coś wniosła — to one obowiązują tam, gdzie żadna warstwa się nie wypowiedziała.

Ustawienie jest przypisywane warstwie o najwyższym priorytecie, która je ustawia, niezależnie od wartości, jaką ta warstwa zapisuje. Plik konfiguracyjny zapisujący wbudowaną wartość domyślną lub powtarzający wartość ustawioną już przez plik poniżej jest wskazywany jako źródło: to on utrzymuje tę wartość. Plik ustawia ustawienie, zawierając jego klucz, łącznie z towarzyszącym kluczem _append listy, a zmienna środowiskowa — będąc wyeksportowaną z niepustą wartością. Plik konfiguracyjny należący do potoku nigdy nie jest wskazywany dla klucza, którego nie zawiera. aggrega config show --origin raportuje według tej samej zasady.

Każde ustawienie zadeklarowane przez schemat konfiguracji jest uwzględnione, choć nie każde ma własny wiersz. Addytywny klucz towarzyszący _append listy jest raportowany w wierszu listy, do której dodaje, więc warstwa wnosząca coś wyłącznie przez ten klucz jest wskazana w wierszu listy, a klucz towarzyszący nie ma własnego wiersza. Ustawienie wewnątrz wpisów listy — polityka zaufania rejestru, dane wejściowe dołączenia pluginu — jest objęte wierszem tej listy.

Dwa dodatkowe ograniczenia, z których każde sprawia, że odpowiedź jest mniej szczegółowa, niż się wydaje.

  • Ustawienie typu lista lub mapa jest przypisywane w całości warstwie o najwyższym priorytecie, która je ustawia. Przypisanie poszczególnych wpisów nie jest śledzone, więc lista złożona z dwóch warstw wskazuje tylko tę o wyższym priorytecie, a wpisu wniesionego przez niższą warstwę nie da się odróżnić od wpisu zapisanego przez wyższą.
  • Wymóg podpisywania jest przypisywany pierwszej warstwie, która go włączyła, a nie ostatniej, która o nim wspomniała. To ustawienie składa się tak, że wygrywa każda warstwa, która je włącza, i żadna późniejsza warstwa nie może go wyłączyć, więc to pierwsza warstwa, która je włączyła, nadała mu efektywną wartość. Warstwa zapisująca required: false niczego nie włącza, więc gdy każda warstwa, która o nim wspomina, zapisuje false, ustawienie raportuje (built-in defaults).

Każda raportowana wartość jest wynikiem rozstrzygnięcia z chwili, gdy dany obszar roboczy został po raz pierwszy wskazany. Edycja pliku konfiguracyjnego nie zmienia tu wartości; zmienia ją ponowne uruchomienie demona. Jest to celowe — wartości te stanowią konfigurację, w której udzielana jest odpowiedź na każde inne żądanie dotyczące tego obszaru roboczego, i dzięki temu można je porównać z katalogiem głównym i warstwą konfiguracji zgłoszonymi dla niego podczas uzgadniania. Klient wyświetlający konfigurację obok pliku edytowanego przez użytkownika powinien informować, którą z tych dwóch rzeczy pokazuje.

Przypisanie do warstw jest ustalane w chwili zapytania, na podstawie plików w ich bieżącym stanie. Dlatego plik konfiguracyjny zmieniony później może przesunąć source, podczas gdy wartość obok pozostaje taka, jak została rozstrzygnięta. Obie części odpowiadają na różne pytania — co obowiązuje i która warstwa o tym zdecydowała — a ustalona jest tylko pierwsza. Aby je ponownie zsynchronizować, należy uruchomić demona ponownie.

Metoda tylko raportuje i nigdy nie zapisuje. Nie zmienia konfiguracji, nie tworzy plików i niczego nie rozstrzyga z rejestru ani z sieci.

Zawartość pojedynczych plików warstw nie jest tu udostępniana. Wiersz poleceń potrafi wypisać dosłownie bajty jednej warstwy, z zachowaniem komentarzy i formatowania; ta metoda raportuje rozstrzygnięcie, a nie bajty. Klient potrzebujący tekstu warstwy ma jej ścieżkę w layers i może ją otworzyć.

Co pozostawia zapis konfiguracji

aggrega/configInit i aggrega/configCapture tworzą dokument konfiguracji i oba go zapisują. Odpowiedź wskazuje plik; jego otwarcie jest kolejnym krokiem, a nie zamiennikiem zapisu. Żadne z nich nie przekazuje treści do samodzielnego umieszczenia, chyba że wprost się o to poprosi, ponieważ funkcja, której wynikiem jest nigdy niezapisany dokument, to inna funkcja pod tą samą nazwą.

Obie różnią się zasięgiem, a każda odpowiedź mówi, jakim. Należy to odczytać przed pokazaniem wyniku.

  • Inicjalizacja domyślnie zapisuje konfigurację współdzieloną przez wszystkie przestrzenie robocze na maszynie. Rejestr i zaufane w nim tożsamości są zwykle takie same niezależnie od miejsca pracy, dlatego wpis trafia tam, chyba że żądanie wyśle workspace: true. scope zawiera zapisany plik configFile oraz machineWide, mówiące, czy jest to plik współdzielony — wyprowadzone z pliku, na który rozwiązał się zapis, a nie z tego, o co prosiło żądanie, więc odpowiedź nie może opisać zmiany obejmującej całą maszynę jako lokalnej.
  • Zamrażanie nigdy nie sięga poza przestrzeń roboczą. Nie przyjmuje celu zapisu ani nadpisania: jego jedynym celem jest uczynienie jednego projektu samowystarczalnym, więc zawsze zapisuje własny plik .aggrega-config.yaml tego projektu. Dlatego jego odpowiedź zawiera configFile i workspaceRoot i nie deklaruje zasięgu — nie ma zasięgu do podania.

Inicjalizacja odmawia zamiast nadpisywać. Istniejący już plik konfiguracji pozostaje nietknięty, a odmowa go wskazuje, ponieważ inicjalizacja służy konfiguracji, która jeszcze nie istnieje, podczas gdy współdzielony zapis, do którego deleguje, z założenia scala. Aby mimo to zapisać, należy wysłać force; wpis rejestru zostaje scalony z istniejącą treścią, a pozostałe ustawienia są zachowane. Odrzucone żądanie nie zmienia niczego.

trust mówi, co stało się z polityką ogłoszoną przez rejestr, jako osobne wyniki, a nie jako opis tekstowy. pinned oznacza, że rejestr ogłosił politykę i została ona przyjęta, a identities podaje liczbę tożsamości. notAdvertised oznacza, że rejestr zapytano i nie ogłosił żadnej, co nie jest błędem — inicjalizacja przebiega dalej, a reason mówi, co zrobił punkt końcowy. Rejestr, z którym nie udało się połączyć, jest zgłaszany tak samo, ponieważ nie wróciła żadna polityka, a inicjalizacja również przebiega dalej; dodatkowo zawiera unreachable tam, gdzie sam błąd pokazuje, że rejestru nigdy nie osiągnięto: jego nazwa się nie rozwiązała, połączenie zostało odrzucone lub nie dało się go otworzyć albo nie udało się nawiązać bezpiecznego połączenia. Rejestr, który odpowiedział — komunikatem not-found lub statusem błędu — nigdy nie zawiera unreachable, dlatego aby odróżnić rejestr niepublikujący polityki od takiego, którego nigdy nie zapytano, należy odczytać ten klucz, a nie treść reason. baseline oznacza, że przypięto wbudowaną bazową politykę oficjalnego huba, ponieważ nie przyjęto żadnej ogłoszonej polityki, a reason mówi dlaczego; wpis zawiera politykę, więc nie trzeba niczego przypinać ręcznie. Oba klucze odpowiadają na różne pytania, więc hub, który zapytano i który niczego nie ogłosił, zawiera oba, a hub w przestrzeni roboczej offline — nigdy niezapytany — zawiera wyłącznie baseline, z reason mówiącym, że przestrzeń robocza jest offline. Każdy inny rejestr, który niczego nie ogłasza, zawiera wyłącznie notAdvertised, jest inicjalizowany bez polityki, a zalecenie brzmi: przypiąć tożsamości ręcznie; w trybie offline żądanie jest odrzucane zamiast obsłużone. skipped oznacza, że nie podjęto próby pobrania. Klient traktujący cokolwiek poza pinned jako błąd zgłaszałby działającą konfigurację jako uszkodzoną.

W trybie dryRun nic nie jest tworzone. written ma wartość false, content zawiera dokument, który utworzyłby zapis, a plikiem, dla którego jest ta treść, jest scope.configFile. Nie powstaje żaden katalog ani nie jest modyfikowany żaden plik, więc edytor może pokazać tekst autorowi i pozwolić mu go zapisać, poprawić lub odrzucić.

Przebieg próbny różni się od zapisu dokładnie jednym — nie zapisuje — więc każdą odmowę, którą wykonuje zapis, wykonuje także on. Najważniejsza jest tu odmowa dla istniejącego pliku: dryRun dla już istniejącego pliku konfiguracji zostaje odrzucony ze wskazaniem pliku, dokładnie tak jak zapis. Dzięki temu odpowiedź może służyć jako predykat — jeśli przebieg próbny odmawia, zapis również by odmówił, z tego samego powodu i z tym samym komunikatem. Aby zamiast tego otrzymać scalenie, które dałby zapis nadpisujący, nadal niczego nie zapisując, należy wysłać force razem z dryRun. W obu trybach rejestr jest odpytywany o ogłoszoną politykę zaufania, ponieważ polityka w tej treści to polityka, którą przypiąłby zapis.

To, co zgłasza zamrożenie, jest tym, co zapisało, a nie jego opisem. sockets wymienia każde zamrożone gniazdo pluginu wraz z zamrożonymi w nim powiązaniami; catalogDirs zawiera katalogi katalogów. Oba są zawsze tablicami — pustymi zamiast nieobecnych.

  • socket i field to nie ten sam ciąg, a różnica nie jest kosmetyczna. socket wskazuje gniazdo, w którym powiązania są osadzone; field to klucz, pod którym zapisano je w pliku. Różnią się tylko dla gniazda dostawcy, zapisywanego pod kluczem w liczbie mnogiej — dlatego field należy użyć, wskazując czytelnikowi wiersz w dokumencie, a socket, nazywając samo gniazdo.
  • Każde powiązanie zawiera uri, capability, function i role, obecne tylko tam, gdzie powiązanie je ma. Identyfikują one powiązanie, zamiast odtwarzać je w całości: opcjonalne dane wejściowe powiązania są zamrażane w pliku dosłownie i nie są powtarzane w odpowiedzi. Plik jest kopią wiążącą.
  • captured: false oznacza sukces. Projekt, którego konfiguracja nie uczestniczy w budowaniu, nie ma nic krytycznego dla budowania do zamrożenia, więc plik pozostaje bez zmian, a obie listy wracają puste. Traktowanie tego jako błędu zgłasza zdrową przestrzeń roboczą jako uszkodzoną.

Domyślnie zamrażane jest tylko to, co określa bajty wyniku — powiązania dostawców oraz powiązania zarządcze przekształcające etykiety. Bramki werdyktów zarządczych i linterów oraz gniazdo importu są pomijane, ponieważ mają się różnić między środowiskami, a ich zamrożenie przeniosłoby bramki jednego środowiska do każdej kopii roboczej. allPlugins: true rozszerza zbiór na każde gniazdo pluginu. Przynależność określa się dla powiązania, a nie dla gniazda, więc gniazdo zarządcze z jednym powiązaniem przekształcającym etykiety i jednym powiązaniem werdyktu wnosi domyślnie tylko pierwsze.

Każda wartość jest zamrażana w swojej wartości efektywnej — tej, która wynika ze scalenia konfiguracji maszyny i własnej konfiguracji projektu — więc powiązanie pochodzące dziś wyłącznie z konfiguracji maszyny zostaje zapisane w projekcie i podróżuje razem z nim. Ustawienia narzędzi obejmujące całą maszynę, w tym polityka zaufania rejestru, nie są krytyczne dla budowania i pozostają na miejscu. Dwukrotne zamrożenie niezmienionej konfiguracji zapisuje te same bajty, więc klient może je swobodnie oferować: drugie wywołanie pozostawia dokument, który czytelnik ma otwarty, dokładnie takim, jaki był.

Co mówi zmiana wtyczki

Wszystkie cztery żądania dotyczące wtyczek domyślnie zapisują, a dzielą się według tego, co zapisują: dwa zmieniają plik konfiguracyjny, a dwa tworzą dokumenty w przestrzeni roboczej. Dwa z nich — dodanie i generowanie — przyjmują dryRun, które wykonuje wszystko inne, co robi żądanie, i niczego nie zapisuje. Należy odczytać z odpowiedzi jej własną informację o tym, gdzie trafiła zmiana, zamiast wywnioskowywać ją z żądania — w przypadku jednego z nich żądanie, które nic nie mówi o zakresie, oznacza najszerszy zasięg.

Dodanie i usunięcie niosą scope, wyprowadzony z pliku, do którego rozwiązał się zapis. configFile to ten plik, machineWide mówi, czy jest to plik, przez który rozwiązuje się każda przestrzeń robocza na tej maszynie, a workspaceRoot wskazuje przestrzeń roboczą, nad którą otwarto tę sesję, więc odpowiedź o zakresie przestrzeni roboczej mówi, o którą przestrzeń chodziło. machineWide jest odczytywane z rozwiązanego pliku, a nie z tego, o co prosiło żądanie, i właśnie to nie pozwala odpowiedzi opisać zmiany obejmującej całą maszynę jako lokalnej.

🔴 Dodanie typu cli, które nie wskazuje ani global, ani workspace, rejestruje polecenie dla całej maszyny. Rozszerzenie poleceń jest narzędziem obejmującym całą maszynę, więc bez nadpisania zapisuje się je w globalnym pliku konfiguracyjnym, przez który rozwiązuje się każda przestrzeń robocza na tej maszynie — a rejestrowane polecenie staje się wtedy poleceniem najwyższego poziomu aggrega dla każdego projektu na tej maszynie, łącznie z projektami, których nikt w tej sesji nie wskazał. Dodanie typu provider, governance, linter lub importer działa odwrotnie: te kształtują kompilację jednego projektu, więc bez nadpisania trafiają do własnego pliku .aggrega-config.yaml tego projektu. Usunięcie podlega tej samej zasadzie dla tych samych typów. Aby zachować rozszerzenie poleceń lokalnie, należy wysłać workspace: true, a aby przenieść dowolny z pozostałych do pliku współdzielonego — global: true; wysłanie obu jest odrzucane. scope w odpowiedzi jest w obu przypadkach wiążącą informacją, a klient powinien ją pokazać przed działaniem na podstawie wyniku.

Dodanie wskazuje, co zostało dodane, a dokładnie jedno z trzech pól mówi, jakiego rodzaju to było. type powtarza typ, dla którego dodano wpis, a następnie: identity niesie samą tożsamość encji przypiętą do wersji dla dołączenia governance, linter lub importer; uri niesie adres artefaktu oci:// wtyczki, wraz z capability, którą teraz obsługuje, dla powiązania provider; a reference niesie przypiętą referencję, której polecenia zarejestrowano, dla instalacji cli. Wywołujący odczytuje więc rodzaj dodanego dołączenia z odpowiedzi, zamiast wyprowadzać go ponownie z wysłanego typu. Usunięcie powtarza type i query obok swojego scope i nic poza tym — o wpisie, którego już nie ma, nie ma nic więcej do zgłoszenia.

Dodanie niesie również written, a przy dryRun — content. written to pole, według którego klient rozgałęzia działanie: wartość true oznacza plik konfiguracyjny, który jest teraz na dysku i który klient może otworzyć, a przy dryRun wartość jest false, a content niesie zamiast tego dokument konfiguracyjny, który wytworzyłby zapis. Oba nigdy nie mają znaczenia jednocześnie, a plik, którego dotyczy content, to scope.configFile, więc nic w odpowiedzi nie niesie drugiej kopii tej ścieżki — co ma tu znaczenie, bo plik dołączenia global to ten, przez który rozwiązuje się każda przestrzeń robocza na tej maszynie.

Wtyczka bez opublikowanej wersji jest odrzucana, a nie dołączana bez przypięcia. Dodanie rozwiązuje zapytanie do jednej wtyczki i przypina jej najwyższą opublikowaną wersję, więc zapisywany wpis niesie wersję. Wtyczka, której repozytorium nie publikuje żadnej zgodnej wersji, jest odrzucana z jej wskazaniem, a wersja wycofana przez wycofanie, któremu ta przestrzeń robocza ufa, jest pomijana na rzecz następnej niższej.

Wersja wskazana w zapytaniu jest przypinana nawet wtedy, gdy została wycofana, i withdrawn to sygnalizuje. query zapisane jako <name>:<version> przypina tę wersję zamiast najnowszej — dla każdego typu oprócz provider, który jest wiązany wyłącznie po nazwie i odrzuca wersję — a wskazanie wersji jest nadpisaniem: jeśli deklaracja wycofania, której ufa ten obszar roboczy, ją wycofała, jest ona przypinana mimo to, a odpowiedź zawiera withdrawn: true — fakt, który aggrega plugin add podaje w terminalu jako wiersz retraction:. withdrawn nie występuje w żadnej innej odpowiedzi, więc jego obecność stanowi cały sygnał — a jego brak nie jest stwierdzeniem, że wersja nie została wycofana. Jeśli nie udało się odczytać znaczników wycofania wskazanej wersji, withdrawn nie występuje, a retraction zawiera unscreened z podaniem przyczyny, tak jak w przypadku dodania niewskazującego wersji, które napotka ten sam błąd; dodanie niewskazujące wersji podaje natomiast w retraction, do jakiego wniosku doszło sprawdzenie wycofania w odniesieniu do wybranej przez nie wersji.

Wyrównanie zgłasza, czy cokolwiek zmieniło, i to jest pole, na podstawie którego należy działać. changed odróżnia zapis od wyrównania, które zastało rekordy już poprawne: niezmieniony plik pozostaje identyczny bajt po bajcie, więc klient przechowujący ten dokument nie ma nic do ponownego wczytania, a dwukrotne wykonanie żądania za drugim razem nie zgłasza zmiany. entity wskazuje plik, hostFunctions niesie wyprowadzony zbiór, a commands niesie odwzorowanie jako wartości, a nie jako wiersz wypisywany przez terminal — każdy wpis to name, opcjonalny description i flags, przy czym każda flaga niesie swoje name oraz opcjonalne shorthand, description, type i default. Zapis jest atomowy, więc klient czytający ten plik w trakcie wyrównania nigdy nie zobaczy częściowego dokumentu.

Generowanie wypełnia dokładnie jedną połowę odpowiedzi, a własne pole dryRun odpowiedzi mówi którą. Domyślnie encje są zapisywane, a notices niesie to, co generowanie zgłosiło o wykonanych zapisach. Przy dryRun nic nie jest tworzone ani modyfikowane: documents niesie każdą wygenerowaną encję jako path, którego dotyczy, oraz jej content, aby klient mógł umieścić je we własnym modelu dokumentów, gdzie są widoczne przed zapisaniem i można je poprawić lub odrzucić. Obie połowy nigdy nie są wypełnione jednocześnie, więc to, który tryb został wykonany, można odczytać z odpowiedzi, a nie z tego, o co proszono.

To, gdzie żądanie dotyczące wtyczki ZAPISUJE, zawsze leży wewnątrz przestrzeni roboczej wskazanej przez to żądanie; to, co CZYTA, jest rozstrzygane dla każdego pola osobno. Bezwzględne miejsce docelowe, takie, które wychodzi poza katalog główny, oraz takie, które wyprowadza poza niego przez dowiązanie, są odrzucane, a nie rozwiązywane — więc generowanie nie może utworzyć encji w drzewie, nad którym sesji nigdy nie otwarto, cokolwiek wyśle. Ścieżka, którą żądanie tylko czyta, to osobna kwestia, rozstrzygana pole po polu, a nie jedną zasadą dla wszystkich: aggrega/pluginGenCatalog czyta moduł i jego nakładkę z dowolnego wybranego miejsca, ponieważ zbudowany moduł leży w katalogu wyjściowym narzędzi, a odmowa odczytu w tym miejscu oznaczałaby odmowę wykonania operacji, której to jest cały cel. aggrega/pluginSync czyta swoje dwie ścieżki wewnątrz przestrzeni roboczej, ponieważ to żądanie dotyczy pliku, który przestrzeń robocza już zawiera. Opisane wyżej żądania lokalizujące przyjmują ścieżkę bezwzględną z jeszcze innego powodu — chodzi o dokument, który klient już ma otwarty, wskazany w zapisie, w jakim go przechowuje.

Żądanie, w którym brakuje czegoś potrzebnego operacji, jest odrzucane ze wskazaniem pola do wysłania. Dodanie lub usunięcie bez type lub query; dodanie provider bez capability albo dodanie governance bez role; dodanie cli bez acceptCapabilities; wyrównanie bez entity lub plugin; generowanie wskazujące oba tryby wyboru lub żaden albo bez overlay lub outputDir. Każde z nich wraca ze standardowym kodem invalid-params, a ponowienie niczego nie zmienia, dopóki nie zmieni się żądanie. Odrzucane jest również usunięcie, którego zapytanie nie pasuje do żadnego wpisu, ze wskazaniem typu, zapytania i przeszukanego pliku — to jest stan konfiguracji, a nie żądania, więc poprawić może trzeba jedno lub drugie.

Nic nie jest wywoływane interaktywnie, a jedyna decyzja, o którą zapytano by człowieka, przychodzi zamiast tego jako pole. Polecenie terminalowe pyta obserwującego, czy akceptuje zadeklarowane możliwości wtyczki rozszerzającej polecenia. Tego strumienia nikt nie obserwuje, więc uzyskanie i wysłanie acceptCapabilities należy do wywołującego, a żądanie, które go nie zawiera, jest odrzucane ze wskazaniem, co wysłać, zamiast instalować na podstawie zgody, której nikt nie wyraził. Demon uruchomiony bez możliwości instalowania rozszerzeń poleceń od razu odrzuca dodanie cli, zamiast zgłaszać sukces, który niczego nie zainstalował.

Które rodzaje można zaoferować autorowi

aggrega/getSchema bez kind odpowiada, jakie rodzaje można wskazać, i odpowiada w dwóch zakresach, ponieważ klient potrzebuje innego zakresu do innego zadania. Należy odczytać ten, o który się pyta.

kinds to każdy token, na który odpowiada plik binarny. entityKinds to zbiór rodzajów, dla których autor pisze dokument. Szeroka lista obejmuje, obok rodzajów tworzonych przez autorów, reprezentację pośrednią, plik blokady, konfigurację przestrzeni roboczej i kontrakty gniazd pluginów — każdy z nich to prawdziwy schemat, ale nie dokument, dla którego ktokolwiek pisze plik. Szeroka lista służy więc do skonfigurowania powiązania schematów w edytorze, a wąska — do zbudowania listy wyboru. Lista wyboru zbudowana z szerokiej listy oferuje wartości, których nie przyjmuje żaden schemat autorski, a autor napotyka odmowę dopiero po wybraniu jednej z nich.

Wąski zbiór jest węższy także od rodzajów encji i żaden schemat nie mówi, o które chodzi. Rodzaj należący do platformy, którego treść zapisuje się w dokumencie innego rodzaju, nie jest dokumentem, od którego autor mógłby zacząć. Takim rodzajem jest Workload: treść workloadu zapisuje się w polu workload: encji Recipe lub FeatureRecipe, bezpośrednio albo w pliku importowanym przez to pole, więc nie istnieje osobny dokument workloadu, do którego można by się odwołać — informacje o tym, gdzie trafia ta treść, zawiera powierzchnia tworzenia encji Workload. Jego schemat ustala apiVersion i kind dokładnie tak, jak schemat rodzaju tworzonego przez autora, ponieważ dzięki temu treść może być walidowana tam, gdzie się znajduje; ustalone wartości identyfikują treść i nie czynią jej adresowalną. Nie są więc sygnałem, że dany rodzaj nadaje się do tworzenia szkicu. Odpowiedź zawiera entityKinds, a nie bajty schematu.

Każdy wpis entityKinds zawiera obie pisownie potrzebne klientowi i żadnej nie da się wyprowadzić z drugiej. kind to token pisany małymi literami z łącznikami — należy go odesłać jako kind do tej metody lub do aggrega/scaffoldEntity. documentKind to wartość, którą sam dokument zawiera w polu kind: najwyższego poziomu. W przypadku rodzaju, którego nazwa składa się z więcej niż jednego słowa, obie różnią się nie tylko wielkością liter: żadna operacja na featurerecipe nie da FeatureRecipe. Należy pobierać każdą z nich z wpisu, zamiast wyprowadzać jedną z drugiej, a wtedy klient nie musi utrzymywać żadnego mapowania.

Każdy wpis mówi także, które operacje przyjmują dokument danego rodzaju, więc kontrolka oferująca te operacje dla dokumentu oferuje tylko te, które nie odrzucają go ze względu na rodzaj. acceptedBy zawiera trzy wartości logiczne, obecne w każdym wpisie, a każda dotyczy dokumentu danego rodzaju wskazanego samodzielnie — przez ścieżkę lub, w przypadku inspekcji, przez nazwę — bez niczego wysłanego obok. singleEntityValidation określa, czy aggrega validate <path> sprawdza dokument danego rodzaju, zamiast go odrzucić i wskazać zakres całego katalogu lub encji Release, który go sprawdza. publication określa, czy aggrega/publishEntity wskazujące sam dokument publikuje go: dla encji Plugin wartość wynosi false, ponieważ jej publikacja wiąże także plik wykonywalny wskazany przez żądanie w plugin, więc żądanie wskazujące tylko dokument zostaje odrzucone; dla encji Manifest i Release wartość wynosi false, ponieważ żaden z tych rodzajów nie jest publikowany. inspectionByName określa, czy aggrega/entityDefinition rozwiązuje nazwę do encji danego rodzaju, przy czym nazwę wysyła się tak, jak zapisuje się ją tam, gdzie jedna encja odwołuje się do innej — encję Plugin jako <pluginType>/<name>, a encję Recipe lub FeatureRecipe jako <capability>/<name> albo samą nazwą, jeśli tylko jedna capability deklaruje tę nazwę. Wartość true oznacza, że operacja nie odrzuca dokumentu z powodu jego rodzaju; nadal może odrzucić konkretny dokument ze względu na jego treść.

Nie należy utrzymywać własnej listy. To, jakie rodzaje istnieją, jest właściwością pliku binarnego, z którym się komunikuje, więc lista zapisana w kliencie jest zgodna w dniu, w którym ją zapisano, i przestaje być zgodna w dniu dodania nowego rodzaju — a autor widzi wtedy, że jego rodzaju brakuje w jedynej kontrolce, która miała go oferować. Należy zapytać, a odpowiedź będzie zgodna z plikiem binarnym.

Obie połowy przychodzą razem i tylko wtedy, gdy nie wskazano żadnego rodzaju. Żądanie wskazujące rodzaj otrzymuje w odpowiedzi schemat tego rodzaju i nie zawiera żadnej z list, więc z odpowiedzi można odczytać, jakie pytanie zadano. Token, na który nie odpowiada żaden schemat, zostaje odrzucony z pełnym zbiorem prawidłowych wartości w komunikacie, ze standardowym kodem invalid-params, więc literówka jest żądaniem do poprawienia, a nie sprawą, o którą trzeba pytać człowieka.

Odpowiada również w pustej przestrzeni roboczej. Słownik jest wkompilowany w plik binarny, więc nie potrzeba dokumentu, pliku blokady ani katalogu — a właśnie w takiej przestrzeni roboczej znajduje się autor rozpoczynający swój pierwszy dokument.

Co daje odpowiedź na żądanie szkieletu

Ta sekcja dotyczy tworzenia szkicu. Druga forma tej metody zapisuje przykład gotowy do uruchomienia, a jej odpowiedź opisano przy metodzie powyżej.

aggrega/scaffoldEntity zwraca tekst. skeleton to YAML dla wskazanego rodzaju: każde pole wymagane przez schemat tego rodzaju, w kolejności, w jakiej schemat je deklaruje. Pole, które schemat ustala na jedną stałą wartość, przychodzi wypełnione — najbardziej widoczne są apiVersion i kind — metadata.name zawiera wysłaną wartość name, a każda inna wymagana wartość przychodzi jako symbol zastępczy o typie zadeklarowanym w tym miejscu przez schemat: pusty ciąg, zero, false, pusta lista, puste mapowanie. kind powtarza token, dla którego wyprowadzono dokument, dzięki czemu klient z kilkoma oczekującymi żądaniami przypisuje odpowiedź na podstawie samej odpowiedzi, bez prowadzenia własnej korelacji.

Metoda niczego nie zapisuje i właśnie to trzeba uwzględnić w projekcie. Nie tworzy pliku, nie wybiera ścieżki i nie dotyka żadnego katalogu. Otrzymuje się dokument do zapisania, a nie dokument zapisany — edytor umieszcza więc tekst w nowym, niezapisanym buforze, który autor może przeczytać, edytować lub odrzucić, a moment, w którym nowy plik trafia na dysk, pozostaje tam, gdzie bufor i historia cofania. Żadne inne żądanie nie przejmuje tego dokumentu i nie umieszcza go gdzieś w imieniu klienta; decyzja o tym, gdzie znajdzie się nowy dokument, należy do edytora.

Metoda niczego nie rozwiązuje i niczego nie potrzebuje od obszaru roboczego. Dokument jest wyprowadzany ze schematów zawartych w pliku binarnym, więc metoda nie łączy się z żadnym rejestrem ani siecią, nie sprawdza żadnego katalogu i nie czyta żadnego pliku. Odpowiada tak samo w każdym obszarze roboczym, w tym w pustym katalogu, w którym nie ma jeszcze żadnego dokumentu Aggrega — a to właśnie obszar roboczy, w którym znajduje się autor zaczynający swój pierwszy dokument i w którym większość innych opisanych tu metod najpierw wymagałaby dokumentu lub pliku blokady.

To samo żądanie daje te same bajty, gdziekolwiek zostanie wysłane. Dokument powstaje w wyniku jednego obliczenia, wspólnego z innymi powierzchniami oferującymi tę możliwość, więc edytor i asystent zapytane o ten sam rodzaj i tę samą nazwę pokazują autorowi ten sam tekst początkowy.

Szkielet zawiera pola wymagane przez jego rodzaj i nie jest gotowym dokumentem. Zawiera pola wymagane i nic poza nimi: potrzebne pole opcjonalne trzeba dodać samodzielnie, a każdy symbol zastępczy to wartość, która wciąż jest należna. Należy wypełnić symbole zastępcze, a następnie uruchomić aggrega/validate na buforze. Dla encji katalogu rodzaju, który aggrega validate sprawdza jako pojedynczą encję, ta metoda wskazuje każdy wciąż należny symbol zastępczy, każdy przy jego kluczu wraz z tym, czego wymaga, według tej samej interpretacji, jaką polecenie stosuje do zapisanego pliku — łącznie z symbolem zastępczym, który schemat dopuszcza jako pusty; najczęściej spotyka się tu capability i implements w szkicu encji Recipe lub FeatureRecipe. Dla każdego innego rodzaju metoda sprawdza bufor względem schematu jego rodzaju, więc symbol zastępczy, którego schemat nie dopuszcza jako pustego — na przykład wersja — wraca jako wynik tego schematu, a taki, który schemat dopuszcza jako pusty, nie powoduje żadnego. Sekcja Walidacja na żywo opisuje wpis, w postaci którego przychodzi każdy symbol zastępczy.

Co mówi odpowiedź importu

aggrega/import przekształca źródło napisane dla innego narzędzia w robocze dokumenty Aggrega i zapisuje je — w odróżnieniu od opisanego wyżej szkieletu, który zwraca tekst. written wymienia każdy plik, który trafił na dysk, względem outputDir; files zawiera każdy plik zapisywany przez żądanie wraz z jego content, niezależnie od tego, czy został zapisany — każdy szkic wytworzony przez importer, a następnie zapis tego, co zapisał import, lub w trybie sync tego, co zmienia synchronizacja. Oba pola odpowiadają na różne pytania, więc należy czytać to, które odpowiada zadawanemu pytaniu: co jest teraz na dysku, czy co zostało wytworzone.

Miejsce szkiców wybiera się samodzielnie lub zostawia katalogowi głównemu obszaru roboczego. outputDir jest opcjonalne, podobnie jak aggrega import --output-dir i output_dir narzędzia import asystenta: żądanie, które go nie podaje, tworzy szkice w katalogu głównym obszaru roboczego — tam, gdzie zapisuje aggrega import uruchomione bez miejsca docelowego, niezależnie od tego, gdzie działa — a żądanie, które go podaje, tworzy je we wskazanym katalogu. Wskazany katalog jest ścieżką wewnątrz obszaru roboczego, a wartość względna jest rozwiązywana względem katalogu głównego obszaru roboczego, a nie katalogu, w którym akurat działa demon. Przekształcane source to inny przypadek i nie podlega temu ograniczeniu: ten plik lub katalog został wybrany przez użytkownika, więc jest odczytywany tam, gdzie się znajduje, a odczyt w tym miejscu nie zmienia miejsca, w którym trafiają szkice. Katalog jest tworzony, jeśli nie istnieje. W trybie dryRun nic nie jest zapisywane, a każdy szkic nadal podaje ścieżkę, dla której jest przeznaczony, względem outputDir podanego w odpowiedzi — wysłanego katalogu lub katalogu głównego obszaru roboczego.

Żądanie nigdy nie nadpisuje encji Aggregate znajdującej się już w outputDir. Aggregate to dokument, który autor dalej edytuje po utworzeniu szkicu, więc żądanie, którego którykolwiek szkic trafiłby do pliku odczytywanego jako Aggregate, zostaje odrzucone ze wskazaniem szkicu i miejsca, w którym znajduje się encja Aggregate, i nic nie zostaje zapisane — również w trybie dryRun, ponieważ przebieg próbny odrzuca to, co odrzuca zapis. Zamiast tego należy wysłać sync, aby zaktualizować ją zgodnie ze źródłem, lub podać inny outputDir, aby utworzyć szkic obok niej. Każdy inny plik istniejący już pod ścieżką szkicu jest nadpisywany, a plik utworzony przez wcześniejszy import, którego ten import nie tworzy, pozostaje na miejscu. Każde żądanie, które tworzy jakikolwiek szkic, zapisuje też w outputDir plik .aggrega-import.json — zapis tego, co zapisał import: target, z którym został wysłany, jeśli go podano, migawkę katalogu, którą odczytał, jeśli jakąś odczytał, oraz każdy utworzony plik, a w utworzonej encji Aggregate lub Release każdy klucz na każdym poziomie zagnieżdżenia wraz ze skrótem zapisanego tam tekstu; każdy inny utworzony plik jest zapisywany w całości — a files i written zawierają go po szkicach. Jest to JSON, więc nic, co odczytuje dokumenty YAML obszaru roboczego, go nie odczytuje; sync, podobnie jak aggrega import --sync, odczytuje go, aby zaktualizować szkice zgodnie z ich źródłem. sync wysłane bez target tworzy szkice dla celu podanego w zapisie, a więc encję Manifest utworzoną przez wcześniejszy import; wysłane z target tworzy szkice dla tego celu, a zapis od tej pory go podaje. Zapisany cel, z którym nie wiąże się żadna encja Recipe w katalogu, jest odrzucany tak jak cel wysłany, a odmowa informuje, że chodzi o cel zapisany. Ponieważ utworzona encja Release jest zapisywana klucz po kluczu, środowisko, które jej autor wpisuje w miejscu, gdzie import zostawił dla niego komentarz, jest kluczem napisanym przez autora, a synchronizacja pozostawia je bajt w bajt.

Należy wysłać sync, aby zaktualizować zgodnie ze źródłem to, co wcześniejszy import utworzył w outputDir, zmieniając tylko to, co zapisał import. Każda część jest oceniana na trzy sposoby — co według zapisu import ostatnio tam zapisał, co jest na dysku i co źródło tworzy teraz. Część, którą źródło pozostawiło tak, jak import ją ostatnio zapisał, pozostaje dokładnie taka, jaka jest na dysku, niezależnie od tego, czy autor ją edytował. Część zmieniona przez źródło jest zapisywana na nowo, część przez nie usunięta jest usuwana — utworzony plik jest kasowany w całości — a część dodana jest umieszczana obok części, które szkic wymienia wokół niej; każde z tych działań następuje tylko tam, gdzie zawartość dysku jest tym, co import ostatnio zapisał, i nie zawiera niczego, co dodał autor. Wszystko inne pozostaje bajt w bajt: klucz dodany przez autora w dowolnym miejscu — parametr, encja Feature, także pod utworzoną instancją encji Component, inna encja Component — komentarz, który nie znajduje się bezpośrednio nad utworzonym kluczem, oraz każdy plik, którego zapis nie wymienia. Synchronizacja w katalogu, który nie zawiera zapisu ani niczego pod ścieżkami szkicu, zapisuje cały szkic, tak jak żądanie bez sync.

drift to to, co synchronizacja zaktualizowała, i jest odpowiedzią na pytanie „czy źródło się zmieniło”. Wymienia każdą część zmienioną przez synchronizację — lub, w trybie dryRun, każdą część, którą by zmieniła — w kolejności, w jakiej wymienia je szkic, każdą jako change (added, removed lub changed), file, czyli utworzony plik, w którym się znajduje, względem outputDir, oraz key, czyli klucze prowadzące do niej w utworzonej encji Aggregate lub Release w postaci listy, dzięki czemu klucz zawierający kropkę pozostaje jednym wpisem; key jest puste, gdy częścią jest cały plik — w ten sposób nazywany jest utworzony plik usuwany przez synchronizację. aggrega import wypisuje te same wpisy na standardowe wyjście błędów jako <change> <key> in <file> lub <change> <file>, a jego kod wyjścia w trybie --sync --dry-run informuje, czy źródło się zmieniło; ten interfejs nie ma kodu wyjścia, więc należy wysłać sync z dryRun i sprawdzić, czy drift jest puste. drift jest pustą listą dla żądania, które nie jest synchronizacją, dla synchronizacji zgodnej ze źródłem oraz dla synchronizacji, której importer nie mógł zakończyć działania. W trybie sync pole files zawiera każdy utworzony plik zmieniany przez synchronizację wraz z nadawaną mu treścią, a następnie zapis, jeśli on również się zmienia, a written wymienia te, które trafiły na dysk — więc zgodna synchronizacja zwraca oba pola jako puste listy. Utworzony plik usuwany przez synchronizację jest wymieniony w drift i w żadnej z tych list: jego wpis removed z pustym key jest jedyną informacją o nim w odpowiedzi, a w trybie dryRun wskazuje plik, który zapis by usunął.

Synchronizacja nigdy nie nadpisuje tego, co napisał autor, lecz zostaje odrzucona. Synchronizacja, która zmieniłaby lub usunęła część edytowaną przez autora, dodała część tam, gdzie autor już ją napisał, lub usunęła część zawierającą coś, co dodał autor, zostaje odrzucona ze wskazaniem każdej takiej części i przyczyny w osobnym wierszu, w sformułowaniach używanych przez aggrega import --sync — <file> <key>: <why> lub <file>: <why> dla całego pliku — i nic nie zostaje zapisane; komentarz umieszczony bezpośrednio nad utworzonym kluczem jest edycją tego klucza. Synchronizacja obejmująca encję Aggregate, której nie wymienia żaden zapis, zostaje odrzucona ze wskazaniem encji Aggregate i zapisu, podobnie jak synchronizacja, której zapisu nie można odczytać, ponieważ bez zapisu nie da się odróżnić jej części od części autora. Obie odmowy są zwracane jako błąd invalid-params, również w trybie dryRun, i wskazują sync. Należy ręcznie uzgodnić każdą wskazaną część lub przywrócić to, co zapisał tam import, i ponownie wysłać żądanie.

🔴 halted: true nie jest błędem, a traktowanie go jako błędu to pomyłka, przed którą należy się zabezpieczyć w projekcie. Importer, który nie mógł przekształcić wszystkiego, nadal tworzy szkice tego, co mógł: odpowiedź zawiera te szkice, written je wymienia, a diagnostics informuje, co pominięto. To najbardziej użyteczna odpowiedź, jaką daje ta operacja, i przychodzi jako wynik, a nie jako niepowodzenie, właśnie po to, aby można było pokazać autorowi obie połowy. W trybie sync ta sama odpowiedź niczego nie zapisuje — files, written i drift są puste — ponieważ częściowy szkic wyglądałby jak źródło, które usunęło każdą część, do której importer nie dotarł. Źródło, którego importer w ogóle nie mógł odczytać, to inny przypadek i jest zwracane jako błąd.

Każdy komunikat diagnostyczny zawiera severity i message, a także code, jeśli importer go nadał. Należy rozgałęziać logikę na podstawie code, gdy trzeba zareagować na konkretny warunek, a czytelnikowi pokazywać message; severity pochodzi z tego samego zbioru, w którym raportuje każde gniazdo wtyczek — halt, warn, info — więc halted jest podsumowaniem wpisów, a nie osobną oceną. files, written, drift, diagnostics i decisions są zawsze tablicami — pustymi, a nie nieobecnymi.

decisions mówi, gdzie import zgadywał. Zawiera jeden wpis na każdy węzeł źródła, który importer zmapował, w kolejności importera i dokładnie tak, jak importer go zgłosił: sourceNode, czyli id, type i paramsSummary węzła; candidates, każdy katalogowy Component, który importer dla niego rozważał, jako componentName, score, tier i signals — wkład każdego z jego sygnałów, pod table, category, domainLabels, shape i name; chosen, wybrany target, mode, w jakim go zapisał — reference do istniejącego Component lub draft — oraz tier wyboru; rationale, czyli uzasadnienie; oraz swapHint, czyli jak wybrać inaczej. candidates jest nieobecne, gdy importer nie rozważał żadnego kandydata, chosen — gdy nie dokonał wyboru, a rationale i swapHint — gdy ich nie zapisał. Każda wartość pochodzi od samego importera — sposób oceniania kandydata i progi poziomów to jego wybory — dlatego wpis należy pokazywać jako jego relację z mapowania, a nie jako werdykt. Decyzje przychodzą zarówno pod dryRun, jak i przy halted równym true: domysły częściowego importu to dokładnie to, czego potrzebuje autor, który go przegląda, a importer, który żadnych nie zgłasza, odpowiada pustą listą. Przy pokazywaniu ich jako tekstu warto wiedzieć, że aggrega import już formułuje jedną decyzję jako mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, gdzie wynik jest wynikiem najlepszego kandydata.

Format jest rozpoznawany ze źródła, chyba że zostanie podany. Rozpoznawanie korzysta z sygnatur deklarowanych przez importery — zarówno z katalogu obszaru roboczego, jak i podstawowych importerów kompilatora — które zapisuje encja Plugin każdego importera: składnię, w jakiej czytane jest źródło, nazwy plików, do których sygnatura się stosuje, oraz ścieżki, które sparsowane drzewo musi lub nie może zawierać. Dzięki temu sam demon nie zna żadnego formatu, a format nowego importera jest rozpoznawany bez żadnych innych zmian. Wykrywanie czyta tylko wysłane źródło — w przypadku katalogu tylko pliki wybrane przez wzorce plików sygnatury — i nie korzysta z sieci; każdy czytany plik jest parsowany parserem, który katalog obszaru roboczego udostępnia dla danej składni — lub, dla składni, dla której katalog nie udostępnia parsera, parserem wbudowanym w kompilator — raz dla każdej składni, w której czyta go sygnatura stosująca się do jego nazwy; importer czyta następnie źródło tym samym parserem. Sygnatura bez wzorca plików stosuje się do wysłanego pliku niezależnie od jego nazwy i do żadnego pliku katalogu; sygnatury importerów Langflow, Flowise i n8n są tego rodzaju i czytają JSON, a sygnatura importera Dify czyta YAML, więc rozpoznanie samodzielnie wysłanego pliku czyta go jako JSON i jako YAML, co nie wymaga parsera w katalogu obszaru roboczego: kompilator zawiera parser JSON i YAML, a parser udostępniony przez katalog jest używany zamiast nich. Źródło, do którego nie pasuje żadna sygnatura, jest odrzucane z prośbą o format i z nazwami formatów ogłaszanych przez importery — lub, w przypadku katalogu, z prośbą o jeden z jego plików wysłany osobno albo o format, którego importer deklaruje wzorce plików, z nazwami tylko tych formatów — w ramach warunku No importer recognises the source (Żaden importer nie rozpoznaje źródła); źródło, do którego pasują sygnatury więcej niż jednego formatu, jest odrzucane z ich wymienieniem, w ramach warunku More than one importer recognises the source (Źródło rozpoznaje więcej niż jeden importer). data każdej odmowy zawiera code i shortCode jej warunku, więc klient prosi o format na podstawie kodu, a nie treści komunikatu. Żaden z tych przypadków nie jest zgadywany, ponieważ zgadnięty format wskazuje niewłaściwy importer i daje pewny siebie nonsens. format w odpowiedzi to format faktycznie użyty, wykryty lub podany, więc klient, który go pominął, dowiaduje się, co otrzymał.

Wysłany katalog jest wczytywany do plików wskazanych przez jego importer, a katalog, którego nie da się odczytać, jest błędem. Gdy source wskazuje katalog, importer otrzymuje te jego pliki, które wybierają wzorce plików deklarowane przez jego sygnatury, z pominięciem folderu wyników budowania obszaru roboczego dist/, każdy nazwany ścieżką wewnątrz katalogu, w kolejności posortowanej, obok plików, które jego wpis plugins.importer wymienia pod with.sources. Importer niedeklarujący wzorców plików, katalog bez plików przez nie wybieranych, plik katalogu i plik z with.sources o tej samej nazwie oraz dowiązanie wśród plików czytanych przez import lub dowiązanie do katalogu, które wyprowadza poza katalog — każdy z tych przypadków zwraca błąd z kodem warunku i niczego nie zapisuje.

O tym, który importer działa, decyduje obszar roboczy, a nie żądanie. Format jest rozwiązywany do importera, który go ogłasza wśród wtyczek katalogu obszaru roboczego i podstawowych importerów kompilatora — tego, którego dołącza wpis plugins.importer w konfiguracji obszaru roboczego, jeśli dołącza któryś z nich — więc żądanie nie może wybrać modułu ani wskazać modułu na dysku. Format, którego nie ogłasza żaden importer, jest odrzucany z jego nazwą, a format ogłaszany przez dwa importery, z których żaden nie jest dołączony — w tym podstawowy importer i importer o innej nazwie, który katalog zawiera dla tego samego formatu — jest odrzucany jako niejednoznaczny, a nie rozwiązywany arbitralnie.

Importer podstawowy, którego maszyna jeszcze nie ma, jest pobierany jeden raz, przez pierwszy import, który go potrzebuje. Pochodzi z domyślnego rejestru obszaru roboczego, jest ograniczony do modułu publikowanego przez wydanie kompilatora i weryfikowany tak, jak pull weryfikuje pobieraną wtyczkę — jego podpis zgodnie z polityką zaufania tego rejestru oraz funkcje hosta, których używa — i jest przechowywany w pamięci podręcznej treści obszaru roboczego, która jest jedyną rzeczą zapisywaną na jego potrzeby: bez pliku lockfile i bez wpisu o zaufanych wtyczkach. Każdy kolejny import odczytuje go stamtąd i nie łączy się z żadnym rejestrem. Moduł, który nie przejdzie weryfikacji, jest błędem niosącym kod swojego warunku i nic nie zostaje zachowane; moduł, którego nie można pobrać — obszar roboczy jest offline, jego rejestr jest nieosiągalny lub rejestr go nie zawiera — jest błędem w ramach warunku A plugin’s .wasm is not on this machine (Pliku .wasm wtyczki nie ma na tej maszynie), który podaje importer, jego wersję i to, co umieszcza jego moduł na maszynie. Samo żądanie nie wskazuje żadnego rejestru, a import, dla którego każdy importer i odczytywany katalog są już na maszynie, w ogóle nie korzysta z sieci.

Jeśli obszar roboczy nie wskazuje żadnego folderu katalogu, import odczytuje katalog publikowany przez jego domyślny rejestr. Obszar roboczy, w którym ani workspace.catalog_dirs, ani AGGREGA_CATALOG_DIRS, ani katalog główny nie wskazują folderu katalogu, odczytuje katalog biblioteki standardowej jako jedną podpisaną migawkę, pod catalog/snapshot w swoim domyślnym rejestrze. Migawka jest pobierana jeden raz: jej podpis jest weryfikowany zgodnie z polityką zaufania tego rejestru, po czym jest ona przechowywana w pamięci podręcznej treści obszaru roboczego i odczytywana stamtąd jako folder katalogu, powiązana ze swoim skrótem, bez ponownego pytania o nią żadnego rejestru. Którą migawkę odczytuje żądanie: z upgrade — najnowszą; w przeciwnym razie tę, którą wskazuje zapis w outputDir, pobraną według skrótu, jeśli maszyna jej nie ma; w przeciwnym razie tę, którą obszar roboczy ostatnio pobrał jako najnowszą; w przeciwnym razie najnowszą. Zapis tworzony przez import wskazuje odczytaną migawkę według jej skrótu, więc późniejsze żądanie do tego samego outputDir odczytuje ten sam katalog. W trybie offline żądanie, które musiałoby pobrać migawkę, jest błędem w ramach warunku The workspace is offline and the step needs the network (Obszar roboczy jest offline, a krok wymaga sieci), który podaje, co należy uruchomić, a upgrade jest odrzucane niezależnie od tego, co ma maszyna, ponieważ tylko rejestr może powiedzieć, która migawka jest najnowsza. Rejestr, który nie publikuje żadnej migawki, pozostawia import bez katalogu, a wpis warn w diagnostics o tym informuje. Obszar roboczy, który wskazuje folder katalogu, importuje względem niego i nie pobiera żadnej migawki, a upgrade niczego tam nie zmienia.

Pod dryRun nic nie jest tworzone. written jest puste, files zawiera te same pliki, które wygenerowałby zapis — przy sync pliki, które zapisałaby synchronizacja, obok drift, który by zaktualizowała — i żaden katalog nie jest tworzony, więc edytor może przedstawić je autorowi do zapisania, poprawienia lub odrzucenia. Wszystko inne, co robi zapis, zostaje wykonane: ten sam importer działa na tym samym źródle i zgłasza te same diagnostyki, więc źródło, które zapis by odrzucił, jest odrzucane również tutaj. Podstawowy importer lub migawka katalogu pobrane pod dryRun są przechowywane w pamięci podręcznej treści tak samo jak przy zapisie, ponieważ pozyskanie tego, na czym działa import, jest częścią jego uruchomienia, a nie umieszczania szkiców.

Ścieżka zwrócona przez importer jest utrzymywana wewnątrz outputDir. Ścieżki szkiców pochodzą od importera, a nie z żądania, więc ścieżka wychodząca poza katalog wyjściowy jest odrzucana i nic nie zostaje zapisane — nawet szkice o poprawnych ścieżkach. Odmowa podaje niewłaściwą ścieżkę, co wskazuje, że poprawić należy importer, a nie żądanie.

Na jakie pytanie odpowiada każde żądanie dotyczące encji

Cztery żądania opisane tutaj zwracają informacje o encji i nie są wymienne. Wybór między nimi zależy od tego, czym się dysponuje w chwili zadawania pytania.

Dysponujesz kursorem. aggrega/hover i aggrega/resolve przyjmują plik i pozycję i na podstawie tego, co tam zapisano, ustalają, o którą encję chodzi. Obejmują kształty odwołań, które faktycznie występują w dokumencie — wartość extends, typ komponentu lub funkcji, implements encji Recipe, odwołania do receptur w encji Manifest, dwa wskaźniki ścieżek encji Release, cel uses oraz własne metadata.name encji. Należy po nie sięgać, gdy współrzędną jest kursor użytkownika: użytkownik czyta dokument i chce wiedzieć, na co wskazuje odwołanie.

Dysponujesz nazwą. aggrega/entityDefinition przyjmuje tożsamość wprost. Nic nie musi być otwarte, pozycja nie ma znaczenia, a encja nie musi być wspomniana nigdzie, gdzie klient mógłby ją znaleźć. Należy po nie sięgać, gdy użytkownik wpisał nazwę, wybrał ją z listy lub przeszedł do czegoś, czego tożsamość własny klient już zna — hover wymaga najpierw znalezienia miejsca, w którym nazwa jest zapisana, a tej pracy nie trzeba wykonywać.

Nie dysponujesz jeszcze niczym. aggrega/catalogIndex wylicza, co zawiera obszar roboczy, wraz z polami opisowymi każdej encji. Należy po nie sięgać, aby wypełnić listę wyboru, a następnie przekazać wybraną nazwę do aggrega/entityDefinition.

Dysponujesz encją Release. aggrega/releaseClosure odpowiada na pytanie o encję Release, a nie o pojedynczą encję; opisano je w sekcji poniżej.

Definicja zwracana przez żądanie według nazwy to encja w postaci rozwiązanej, a nie taka, jaką deklaruje którykolwiek pojedynczy plik. Encja Component lub Feature rozszerzająca bazę wraca z kontraktem tej bazy, który nie występuje nigdzie w dokumencie deklarującym jej nazwę — odpowiedź dotyczy więc tego, czym encja jest, a samodzielne odczytanie pliku nie dałoby tego samego.

Przychodzi ona jako dokument YAML, a nie jako struktura wewnątrz odpowiedzi, i jest to celowe: filar schematu ma kilka kształtów zapisu — treść wypisaną wprost, odwołanie do współdzielonego dokumentu lub znacznik mówiący, że treść pochodzi z bazy — a dokument odtwarza ten, do którego doszło rozwiązywanie, w kolejności kluczy nadanej przez autora. Jeśli potrzebne są jego pola, należy go sparsować jako dokument; jeśli ma trafić do panelu, można go pokazać bez zmian.

Rozróżnianie dwóch odmów dla żądań według nazwy

Nazwa, która nie rozwiązuje się do niczego, jest odrzucana zamiast zwracać pusty dokument, ponieważ pusta odpowiedź przedstawiałaby literówkę jako encję, która nie ma nic do powiedzenia o sobie. Nazwa może nie rozwiązać się do niczego na dwa sposoby, wymagające od czytelnika różnych działań, i rozróżnia się je po tym, co zawiera data błędu, a nie po treści komunikatu:

  • Brak file w data. Nic w obszarze roboczym nie deklaruje tej nazwy i żaden poziom katalogu jej nie rozwiązuje. Niemal zawsze to żądanie należy poprawić — literówka lub nazwa z katalogu, którego ten obszar roboczy nie ma na ścieżce wyszukiwania.
  • file w data. Dokument obszaru roboczego deklaruje tę nazwę, a katalog mimo to nic dla niej nie rozwiązał. Encja jest zapisana, ale coś ją odrzuciło — to stan obszaru roboczego, który naprawia człowiek. Gdy tę nazwę deklaruje dokładnie jeden dokument, który katalog odczytał i odrzucił — co jest typową przyczyną — komunikat zaczyna się od tej odmowy, podanej raz: jej kategorii i krótkiego kodu, dokumentu według ścieżki, pod którą jest zgłaszany, oraz tego, co jest z nim nie tak, np. wiersza i naruszanego ograniczenia; następnie odnotowuje, że plik pominięto przy wczytywaniu, i wymienia pozostałe pliki odrzucone przy wczytywaniu. W przeciwnym razie komunikat wskazuje dokument deklarujący, wymienia pliki odrzucone przy wczytywaniu i podaje, skąd ten obszar roboczy wczytuje encje lokalne i co zmienić, aby dokument został wczytany — tego wyjaśnienia brak, gdy nazwę deklaruje odrzucony dokument, bo taki dokument już znajduje się tam, skąd czyta katalog.

Oba niosą kod entity-not-resolvable, dlatego należy rozgałęziać na podstawie obecności file, a nie kodu.

Pytanie o współrzędną

Dysponujesz odwołaniem do rejestru. Należy wysłać je jako name w aggrega/entityDefinition; odpowiedzią jest encja opublikowana pod tą współrzędną, w tym samym kształcie wyniku, jaki otrzymuje nazwa, z dodatkowym published, wypełnionym na podstawie tego, co opublikowano, a nie tego, co rozwiązał katalog:

  • definition to dokument encji dokładnie w takiej postaci, w jakiej go opublikowano. Współrzędna, której encję opublikowano wraz z deklarowanymi przez nią plikami, zawiera archiwum, z którego dokument jest rozpakowywany; współrzędna, której encja nie deklaruje żadnego pliku, zawiera dokument bez zmian, a encja Plugin jest odczytywana z manifestu, a nie z opublikowanego z nią pliku wykonywalnego. Dziedziczenie nie jest stosowane.
  • authoredLength to długość tego dokumentu, ponieważ definicja jest tu dokumentem autorskim, a nie renderingiem dokumentu rozwiązanego.
  • file jest puste, ponieważ encja odczytana z rejestru nie ma na tej maszynie dokumentu, który można by wskazać.
  • publishScope jest pomijane: współrzędna jest już znana, a to właśnie miejsce publikacji encji.
  • published opisuje to, co odczytano, i występuje w tej odpowiedzi, a w żadnej odpowiedzi według nazwy: reference; archive, czyli czy bajty były archiwum, z którego rozpakowano dokument — false, gdy współrzędna zawierała sam dokument; mediaType deklarowany przez manifest; oraz manifestDigest tego manifestu, który można wysłać po @ zamiast tagu, aby ponownie odczytać dokładnie te same bajty.

Żądanie łączy się z rejestrem wskazanym w odwołaniu, z poświadczeniami użytkownika, jako który działa ten demon, i zgodnie z ustawieniami sieci tego obszaru roboczego, więc obszar roboczy w trybie offline je odrzuca. Pobrane bajty są sprawdzane wobec skrótu, który zapisuje dla nich manifest artefaktu, i wobec niczego innego — żaden podpis nie jest weryfikowany, żadne wycofanie nie jest zgłaszane — i nic nie jest zapisywane. Odwołanie, którego nie można odczytać, jest odrzucane z kodem entity-not-resolvable, a komunikat zaczyna się od krótkiego kodu warunku wyjaśniającego przyczynę — tych samych warunków, które zgłasza aggrega inspect — i kończy informacją, co z tym zrobić. Odwołanie, które nie wskazuje repozytorium ani tagu czy skrótu, jest błędnie sformułowanym żądaniem i jest odrzucane jako invalid params.

Domknięcie to nie graf

aggrega/irGraph i aggrega/releaseClosure wynikają z tego samego rozwiązania tej samej encji Release i odpowiadają na różne pytania. Klient, który już otrzymuje graf, może rozsądnie założyć, że ma również tę informację, a tak nie jest.

Graf mówi, co wdraża Release — jego węzły, granice, w których się znajdują, co jest z czym połączone oraz wartości i załączniki, które niesie każdy węzeł. To jest obraz.

Domknięcie mówi, co zostało pobrane do jego zbudowania i w jakich wersjach. Każda encja, do której sięga Release, niezależnie od tego, czy stała się węzłem; współdzielone dokumenty, z których te encje korzystają; oraz wtyczki kształtujące wynik. To jest wykaz materiałów.

Żadnego z nich nie da się odtworzyć z drugiego. Do encji można sięgnąć, choć nigdy nie pojawi się jako węzeł — encja Recipe, na którą Manifest mapuje typ komponentu, jest osiągana przez każdą kompilację i nie jest węzłem w żadnej z nich — a węzeł nie niesie wersji, do której rozwiązał się jego typ. Zatem czytelnik pytający „dlaczego ta wersja się zmieniła?”, „na co wpłynęłaby zmiana tego współdzielonego dokumentu?” lub „od czego ta encja Release faktycznie zależy?” pyta o domknięcie, a czytelnik pytający „co wdraża ta encja Release?” pyta o graf.

Czego nie robi żądanie domknięcia. Niczego nie renderuje i nie publikuje niczego z tego, co znajdzie. W szczególności nie zgłasza ostrzeżenia o dryfie ani porady renderowania: należą one do żądania, które o nie prosiło, a publikowanie zastępuje całą warstwę diagnostyki, więc listing, który by publikował, wymazałby to, co żądanie grafu już przedstawiło użytkownikowi. Aby uzyskać werdykt dotyczący dryfu, należy poprosić o graf. Jedyna rzecz, którą publikuje, nie jest jego własnym ustaleniem: żądanie, które stwierdzi brak pliku lockfile, wycofuje oparte na nim ostrzeżenie o dryfie, niezależnie od tego, jakie to żądanie — zob. Świadomość pliku lockfile.

Wymaga pliku lockfile, tak jak graf. Wersje zgłaszane w listingu to te, do których rozwiązała się ta encja Release, a w obszarze roboczym, którego nikt nie przygotował, nie zostały jeszcze rozwiązane. Listing utworzony bez niego zgłaszałby to, co katalog akurat dziś zawiera, a to inne pytanie niż to, od czego zależy ta encja Release. Odmowa wskazuje plik lockfile i encję Release, więc klient może od razu zaproponować aggrega pull --release <release>.

kind we wpisie domknięcia występuje tylko tam, gdzie jest znany. Odwołanie jest zbierane z pozycji w dokumencie, a niektóre pozycje mówią, na jaki rodzaj wskazują, inne zaś nie. Pole jest zgłaszane tam, gdzie miejsce odwołania je zapisało, i pomijane tam, gdzie tego nie zrobiło, zamiast być zgadywane z kształtu nazwy. Jest zgłaszane jako słowo, które autor pisze na początku dokumentu, czyli to samo słowo, którego każda powierzchnia zgłaszająca domknięcie używa dla tego samego wpisu.

To samo słowo prosi o ten sam dokument gdzie indziej. aggrega inspect <release> --closure odpowiada na to pytanie w wierszu poleceń, a tryb release narzędzia describe odpowiada na nie przez protokół narzędzi asystenta. Wszystkie trzy wykonują jedno rozwiązanie nad encją Release, więc nie mogą się rozejść co do tego, od czego zależy Release. Zob. aggrega inspect „The dependency closure”.

Model pamięci podręcznej

Operacje są sterowane pamięcią podręczną: przed wywołaniem hover / completion / resolve / diagnostics dla pliku należy wywołać dla niego aggrega/validate. To wywołanie zasilające nie potrzebuje encji Release — walidacja, która żadnej nie wskazuje, nadal parsuje bufor i wypełnia pamięć podręczną — więc te operacje działają w obszarze roboczym, który nie ma encji Release do wskazania. Pamięć podręczna parsowania jest przy każdym odczycie sprawdzana względem czasu modyfikacji każdego pliku na dysku, więc zewnętrzne zmiany (zapis w edytorze, git checkout) są wychwytywane automatycznie — aggrega/invalidate wysyłane przez edytor jest optymalizacją, a nie wymogiem poprawności.

Pamięć podręczna należy do obszaru roboczego, który ją zasilił. Plik zwalidowany w jednym obszarze roboczym jest buforowany dla tego obszaru, więc o tę samą ścieżkę zapytaną w innym obszarze zgłaszana jest informacja, że nie została jeszcze zwalidowana, zamiast odpowiedzi z wpisu pierwszego obszaru. Dzięki temu pytanie o drugi obszar roboczy ani nie daje błędnej odpowiedzi, ani nie kosztuje pierwszego obszaru jego rozgrzanego stanu — a aggrega/invalidate podobnie czyści tylko obszar roboczy, który wskazuje.

Żądanie diagnostyki w trakcie walidacji

Walidacja zasila dwie rzeczy dotyczące pliku — wynik parsowania przekazywany innym operacjom oraz zgłaszane ustalenia — i zasila je w odstępie chwili. aggrega/diagnostics to jedyne żądanie, które odczytuje obie: potrzebuje wyniku parsowania, by wiedzieć, że może odpowiedzieć na temat pliku, a odpowiada na podstawie ustaleń. Żądanie przychodzące między tymi dwoma momentami uznawałoby więc, że może odpowiedzieć, podczas gdy nie byłoby jeszcze czym odpowiedzieć.

Zamiast tego czeka. Jeśli wysłać aggrega/diagnostics dla pliku, który właśnie jest walidowany, odpowiedź nadejdzie po zakończeniu tej walidacji i będzie zawierać jej ustalenia. Dla pliku istnieje jedna poprawna odpowiedź niezależnie od momentu i to ją się otrzymuje — nigdy nie jest to pusta lista dla pliku, którego walidacja zaraz zgłosi błędy; to jedyna błędna odpowiedź, po której klient nie może się podnieść, bo nic nie skłania do ponownego zapytania o plik, o którym powiedziano, że jest czysty. Pozostałe operacje oparte na pozycji — hover, completion, resolve, findReferences, findImplementations — odczytują wynik parsowania i odpowiadają na jego podstawie, więc nie mają na co czekać i nigdy nie czekają.

Dwie rzeczy kończą oczekiwanie wcześniej i obie są już dostępne. Zatrzymuje je $/cancelRequest z identyfikatorem tego żądania oraz kooperacyjne aggrega/shutdown. Żadna z nich nie wymaga niczego dodatkowego w żądaniu.

Oczekiwanie jest też ograniczone. Jeśli walidacja nie zakończy się w budżecie czasu, który daemon jej przydziela, żądanie zostaje odrzucone z kodem walidacji w toku, zamiast otrzymać pustą odpowiedź — zob. Kody błędów. Taka odmowa oznacza, że oczekiwana praca rzeczywiście trwa, więc należy wkrótce zapytać ponownie; nie jest to sygnał do wysłania kolejnej walidacji, która dodałaby pracy i na nic nie odpowiedziała.

Daemon wykonujący żądania pojedynczo odpowiada na nie w kolejności nadejścia, więc nic się nie nakłada i nigdy nie dochodzi do oczekiwania. Daemon wykonujący je współbieżnie odpowiada na te same pytania w ten sam sposób, a to właśnie oczekiwanie to zapewnia: otrzymana odpowiedź jest tą, jaką dałaby kolejność szeregowa.

Rozmiary w odpowiedzi

Odpowiedź, która podaje liczbę bajtów, podaje ją dwukrotnie: jako liczbę oraz jako tę samą wielkość zapisaną słownie. Pole tekstowe nosi nazwę pola liczbowego z dopisanym Text — size i sizeText, totalSize i totalSizeText, reclaimedBytes i reclaimedBytesText i tak dalej w każdej odpowiedzi, która zawiera rozmiar.

Należy wyświetlać postać tekstową, a obliczenia wykonywać na liczbie. Wysyłanie obu ma ten cel, że klient nigdy nie musi sam zapisywać rozmiaru: demon zapisuje go tym samym formaterem, którego używa wiersz poleceń, więc aggrega cache status i aggrega/cacheStatus pokazują daną pamięć podręczną identycznie, aż do zaokrąglenia. Klient, który składałby własny tekst, rozjechałby się z tym przy pierwszej niezgodności co do wartości granicznej.

Postać tekstowa używa jednostek binarnych — 512 B, 1.0 KiB, 5.0 MiB, 3.0 GiB — czyli tego samego słownictwa, które aggrega/cacheEvict przyjmuje w maxSize, więc rozmiar odczytany z jednej odpowiedzi można odesłać w następnym żądaniu bez przepisywania. Powyżej bajtów tekst zawiera jedno miejsce po przecinku, dzięki czemu podaje wielkość tak, jak czytelnik chce ją widzieć, a nie z dokładnością do bajtu; gdy potrzebna jest dokładna wartość, służy do tego pole liczbowe.

Tam, gdzie liczba jest opcjonalna, tekst jest opcjonalny razem z nią i nigdy nie występuje tylko jedno z nich: rozmiar pluginu w odpowiedzi na publikację zawiera pluginSize i pluginSizeText razem albo nie zawiera żadnego.

Każde żądanie wskazuje obszar roboczy, którego dotyczy

W każdym żądaniu należy wysyłać workspaceRoot: ścieżkę bezwzględną katalogu głównego obszaru roboczego, na którym to żądanie działa. Demon nie ma własnego obszaru roboczego i nie zapamiętuje żadnego między żądaniami, więc odpowiedź na żądanie dotyczy wskazanego w nim obszaru roboczego i niczego innego. Dwa żądania wskazujące dwa obszary robocze otrzymują dwie odpowiedzi i żadne z nich nie widzi encji, encji Releases, zbuforowanych wyników parsowania ani diagnostyk drugiego.

Żądanie, które nie wskazuje żadnego, jest odrzucane standardowym błędem invalid-params, który podaje nazwę parametru; tak samo pusta wartość, która nie wskazuje żadnego obszaru roboczego i jest traktowana jak brakująca. Z tego samego powodu odrzucane są dwie inne postacie, każda nazwana w komunikacie: ścieżka względna, ponieważ katalog główny obszaru roboczego nie ma względem czego być względny; oraz ścieżka, która nie jest istniejącym katalogiem, ponieważ obszar roboczy jest drzewem.

Trzy żądania nie potrzebują workspaceRoot, każde dlatego, że jego przedmiotem nie jest obszar roboczy. aggrega/getSchema i aggrega/scaffoldEntity odpowiadają na podstawie schematów wkompilowanych w uruchomiony plik binarny, więc obszar roboczy nie wnosi nic do żadnego z nich — i dlatego oba mogą odpowiadać w katalogu, którego nikt nie przygotował. Trzecim jest aggrega/initialize, w którym obszar roboczy się deklaruje, zamiast na nim działać. Druga forma aggrega/scaffoldEntity, czyli zapisywanie przykładów gotowych do uruchomienia z dokumentacji lub wyświetlanie ich listy, działa na obszarze roboczym, więc żądanie tej formy wskazuje go jak każde inne.

Zbuforowany stan każdego obszaru roboczego jest przechowywany osobno, a wskazanie drugiego nic nie kosztuje pierwszego. Indeks katalogu, bufor parsowania i diagnostyki obszaru roboczego należą do tego obszaru, więc pytanie dotyczące innego miejsca nie usuwa tego, co edytor gromadził dla folderu otwartego przez użytkownika. Dwa zapisy jednego katalogu głównego to jeden obszar roboczy, więc ścieżka zawierająca wewnętrzną . lub podwójny separator trafia do tego samego rozgrzanego stanu co jej zwykła postać.

Deklarowanie obszaru roboczego, dla którego mają być wypychane diagnostyki

Diagnostyki docierają na dwa sposoby: klient o nie prosi albo demon je wypycha. Demon wypycha je tylko dla obszaru roboczego zadeklarowanego podczas uzgadniania połączenia. Każde inne żądanie zwraca swoje wyniki we własnej odpowiedzi i niczego nie wypycha.

Deklaruje się go, wysyłając workspaceRoot w aggrega/initialize. Na tym kończy się działanie deklaracji — niczego nie zakotwicza i żadne późniejsze żądanie nie jest względem niej rozstrzygane.

Powodem tego ograniczenia jest przeznaczenie wypychanej diagnostyki. Wypychanie utrzymuje aktualną listę problemów edytora podczas pisania i jest dokładnie tym, czego nie należy robić z odpowiedzią, której nikt nie chciał zobaczyć: bez tej zasady pytanie dotyczące drugiego obszaru roboczego — zadane na przykład przez inne narzędzie współdzielące demona — zapełniłoby listę problemów czytelnika wynikami dotyczącymi plików, których nigdy nie otworzył. Ograniczenie wypychania sprawia, że pytanie jednego klienta nie trafia na listę problemów innego.

Pole jest opcjonalne, a trzy możliwe znaczenia jego użycia są rozróżnialne:

co jest wysyłanedokąd trafiają wypchnięciaco zgłasza uzgadnianie połączenia
nicobszar roboczy, nad którym uruchomiono procesten obszar roboczy
katalog główny obszaru roboczegoten obszar roboczyten obszar roboczy
pusty ciągnigdzie — żadna diagnostyka nie jest nigdy wypychanapusty katalog główny

Niewysłanie niczego pozostawia wypychanie przy obszarze roboczym, nad którym uruchomiono proces, więc klient, który niczego nie deklaruje, otrzymuje diagnostyki dla tego obszaru roboczego. Wysłanie pustego ciągu to uczciwa deklaracja dla klienta, który nie jest edytorem i nie ma listy problemów do synchronizowania: każdy wynik nadal do niego trafia, w odpowiedzi na żądanie, które go wygenerowało.

Zadeklarowany obszar roboczy jest rozstrzygany dokładnie tak samo jak wskazany w żądaniu, więc deklaracja podająca ścieżkę względną lub ścieżkę, która nie jest katalogiem, jest odrzucana podczas uzgadniania połączenia, zamiast kierować wypchnięcia w nieoczekiwane miejsce.

Katalog główny obszaru roboczego i aktywna encja Release

Demon rozpoznaje każdy obszar roboczy wskazany w żądaniu tak samo, jak robi to każde polecenie aggrega, a Konfiguracja opisuje, co zakotwicza katalog główny i w jakiej kolejności. Dla klienta istotne są dwie konsekwencje. Plik .aggrega-config.yaml bez bloku workspace: niczego nie zakotwicza: nadal wnosi swoje ustawienia, ale sam plik ustawień nie może zamienić każdego katalogu nadrzędnego w katalog główny obszaru roboczego. A gdy nic nie zakotwicza, używany jest katalog roboczy — demon się uruchamia, a operacje po prostu niczego nie rozpoznają, zamiast odmawiać działania.

Proces jest również uruchamiany nad obszarem roboczym, wskazanym przez --workspace-root lub ustalonym przez przejście w górę od katalogu roboczego, a to rozpoznanie robi dwie rzeczy i żadnych innych: określa rozmiar puli procesów roboczych, który jest właściwością procesu, a nie żadnego żądania, oraz stanowi domyślną deklarację dla wypychanej diagnostyki. Żadne żądanie nie jest względem niego obsługiwane.

Konfiguracja to również ta sama kaskada, którą czyta każde polecenie, a opisuje ją Konfiguracja. Demon dodaje jedynie to, że odczyt konfiguracji dla każdego obszaru roboczego jest wykonywany raz, gdy obszar ten zostaje wskazany po raz pierwszy, i ponownie używany przy każdym kolejnym żądaniu jego dotyczącym. Plik konfiguracji, który kaskada by odczytała, a który jest dowiązaniem prowadzącym poza obszar roboczy — własny .aggrega-config.yaml obszaru roboczego lub nakładka należąca do CI obok niego — nie jest odczytywany, tu tak samo jak w terminalu, i w jego miejsce nie jest odczytywane nic innego, co ten plik by skonfigurował. Od terminala różni się to, co nadal odpowiada. Demon uruchomiony nad takim obszarem roboczym startuje i informuje o tym raz w swoim strumieniu błędów; żądanie wskazujące taki obszar jest w obu przypadkach obsługiwane w następujący sposób. aggrega/releaseCandidates i aggrega/catalogIndex — dwa żądania wyliczające zawartość obszaru roboczego — odpowiadają, odczytując go bez żadnej konfiguracji: wyliczane są własne dokumenty obszaru roboczego, żaden katalog katalogu encji nie jest odczytywany, a wstrzymany plik jest wymieniony w unreadLinkedFiles, niezależnie od tego, czy wyszukiwanie na niego trafiło. Po tej nazwie klient rozpoznaje, że konfiguracja obszaru roboczego prowadzi poza niego. Każde inne żądanie wskazujące ten obszar roboczy — kompilacja, graf, walidacja, domyślna encja Release, efektywna konfiguracja, zapis oraz aggrega/catalogIndex w kategoriach encji Release — zależy od tej konfiguracji, więc jest odrzucane błędem invalid-params z kodem E0321 — read-leads-out-of-workspace w polu data błędu — oraz zdaniem wskazującym dowiązanie i miejsce, do którego prowadzi. Uzgadnianie połączenia również odpowiada dla takiego obszaru roboczego, zgłaszając defaults jako configSource, ponieważ żaden plik konfiguracji nie wniósł niczego, czym odpowiadają listy. Po usunięciu dowiązania lub skierowaniu go do pliku wewnątrz obszaru roboczego następne żądanie odczyta konfigurację. Pod plikami projektu znajduje się warstwa globalna: plik wskazany przez --config w wierszu poleceń, które uruchomiło demona, dla każdego obsługiwanego obszaru roboczego; w przeciwnym razie plik wskazany przez zmienną środowiskową AGGREGA_CONFIG, gdy jest ustawiona; a w przeciwnym razie lokalizacja domyślna — w systemie Windows aggrega\config.yaml w katalogu wskazanym przez zmienną środowiskową APPDATA, a w pozostałych systemach aggrega/config.yaml w katalogu wskazanym przez XDG_CONFIG_HOME, z rezerwową lokalizacją ~/.config/aggrega/config.yaml — wczytywana, gdy istnieje. Pod nią znajdują się wbudowane wartości domyślne.

Operacje działające na encji Release przyjmują ją jako parametr; demon sam żadnej nie wybiera. Obszar roboczy nadal deklaruje, na którą encję Release wskazuje, a tę deklarację odczytuje czterostopniowa kaskada: pole konfiguracji build.authoring_release, następnie plik znacznika .aggrega/active-release, następnie heurystyka jednej encji Release w obszarze roboczym, a na końcu rozwiązanie rezerwowe oparte wyłącznie na encji Aggregate. Zapisany znacznik ma więc pierwszeństwo przed heurystyką, a znacznik wskazujący encję Release, której nie można wczytać, przechodzi do heurystyki, a nie do rozwiązania rezerwowego. Znacznik wskazujący encję Release spoza obszaru roboczego — ścieżką bezwzględną, ścieżką wychodzącą poza katalog główny lub przez dowiązanie prowadzące poza niego — nie jest odczytywany, chyba że konfiguracja obszaru roboczego wskazuje tę encję Release jako build.authoring_release lub jako klucz w workspace.releases: to konfiguracja jest sposobem na dotarcie do encji Release przechowywanej poza obszarem roboczym, a znacznik nie. Kaskada przechodzi wtedy dalej dokładnie tak, jak w przypadku znacznika, którego nie może wczytać, a gdy nie ustali niczego, trace podaje przyczynę w wierszu znacznika, a reason w swoim zdaniu o znaczniku.

aggrega/activeRelease zgłasza wybór tej kaskady i jest to sugestia dla klienta, a nie ustawienie, według którego działa demon. Należy pytać demona, zamiast samodzielnie odczytywać dane wejściowe kaskady: pole konfiguracji i plik znacznika to dwa z czterech wejść, więc którekolwiek z nich zostanie odczytane, wskazuje wybór obszaru roboczego tylko wtedy, gdy akurat to ono wygrało. Najwyraźniejszym przypadkiem jest znacznik wskazujący encję Release, której nie można wczytać — kaskada wybiera wtedy zupełnie inną encję Release, a czytający znacznik zgłosiłby tę, której wczytanie się nie powiodło.

Kaskada działa wtedy, gdy się o nią zapyta, i nie wcześniej, co ma dwie konsekwencje, na których można polegać. Uzgadnianie połączenia pozostaje szybkie niezależnie od rozmiaru drzewa, ponieważ nie czeka na przejście obszaru roboczego. A odpowiedź podąża za obszarem roboczym: po zapisaniu znacznika — za pomocą aggrega/setActiveRelease, które w odpowiedzi zwraca sam nowy wybór — edycji konfiguracji, dodaniu lub usunięciu pliku encji Release i ponownym zapytaniu ten sam demon zwraca nową odpowiedź. Zmiana encji Release, na której się pracuje, nigdy nie wymaga ponownego uruchamiania demona — klient wysyła inną wartość release w następnym żądaniu.

Operacje przeszukujące cały obszar roboczy zamiast jednego bufora — completion, hover, resolve, findReferences i findImplementations — wyliczają pliki YAML pod katalogiem głównym obszaru roboczego, a to wyliczanie respektuje .gitignore. Udział ma każdy plik .gitignore od katalogu głównego obszaru roboczego aż do katalogu samego pliku, przy czym wygrywa najbliższy, więc plik YAML ignorowany przez repozytorium nie jest proponowany jako kandydat uzupełniania ani zgłaszany jako definicja czy odwołanie. Plik .gitignore będący dowiązaniem prowadzącym poza obszar roboczy nie jest odczytywany, więc plik znajdujący się gdzie indziej na maszynie nigdy nie decyduje, które dokumenty obszaru roboczego są przeszukiwane. Drzewa dostarczonych zależności i wygenerowane wyniki pozostają więc poza wynikami międzyplikowymi bez osobnego ustawienia wykluczeń do utrzymywania — a dokument, który powinien zostać znaleziony, ale jest ignorowany, się nie pojawi; to jedyny przypadek wart sprawdzenia, gdy wydaje się, że brakuje odwołania. Encje Components i Features, które completion proponuje dodatkowo ze skonfigurowanych catalog_dirs, to inny odczyt: pochodzą z tych katalogów w postaci skonfigurowanej — tych samych, które czyta kompilacja encji Release, gdy konfiguracja nie daje tej encji Release własnych, lub, dla żądania wskazującego encję Release, jej własnych — więc encje katalogu są proponowane niezależnie od tego, czy obejmuje go .gitignore — z wyjątkiem encji znajdującej się za dowiązaniem prowadzącym poza katalog, w obrębie którego muszą pozostać odczyty katalogu; ta nie jest odczytywana ani proponowana.

Żądanie wskazujące encję Release odczytuje katalogi katalogowe tej encji Release, czyli te same, które odczytuje jej kompilacja w terminalu: jej własne, jeśli konfiguracja obszaru roboczego przypisuje jej jakieś w workspace.releases, a w przeciwnym razie catalog_dirs obszaru roboczego. Dotyczy to żądań aggrega/build, aggrega/buildPreview, aggrega/irGraph, aggrega/releaseClosure, aggrega/resolveDependencies, aggrega/validate i aggrega/lint wskazujących encję Release, żądań aggrega/attachCandidates i aggrega/attachmentContainer skierowanych do węzła grafu encji Release, żądania aggrega/connectionAtPosition oraz żądań wymienionych w następnej sekcji, gdy wskazują encję Release. Jedna sesja odpowiada więc na pytania o każdą encję Release w obszarze roboczym, który przechowuje wariant katalogu dla każdej encji Release, każdą z jej własnego wariantu, bez przesyłania niczego poza ścieżką encji Release. Żądanie, które nie dotyczy żadnej pojedynczej encji Release — aggrega/catalogIndex, aggrega/entityDefinition, completion, hover i resolve niewskazujące encji Release oraz aggrega/attachCandidates skierowane do encji lub zbioru etykiet — odczytuje catalog_dirs obszaru roboczego. Wyjątkiem jest aggrega/lint niewskazujące ani encji, ani encji Release w obszarze roboczym, który wymienia encje Releases w workspace.releases: sprawdza wtedy cały katalog raz dla każdej encji Release, za każdym razem w katalogach tej encji Release, jak opisano w sekcji Publikowanie konwencji na żądanie i przy każdej edycji. Zobacz Przypisywanie encji Release własnych katalogów katalogowych.

Odpowiadanie w kategoriach jednej encji Release

aggrega/catalogIndex, aggrega/entityDefinition oraz pięć żądań wychodzących od pozycji kursora — aggrega/hover, aggrega/resolve, aggrega/completion, aggrega/findReferences i aggrega/findImplementations — nie dotyczą żadnej pojedynczej encji Release, a każde z nich przyjmuje opcjonalny parametr release, który sprawia, że dotyczy jednej. Jest to ścieżka względna wobec katalogu głównego obszaru roboczego, podlegająca tej samej umowie co w pozostałych żądaniach przyjmujących encję Release; wartość, która nie wskazuje żadnego pliku encji Release albo wskazuje katalog, jest odrzucana, zamiast otrzymać odpowiedź w kategoriach obszaru roboczego, która wyglądałaby jak odpowiedź w kategoriach encji Release.

Co encja Release obejmuje w każdym z opisanych tu żądań: dokumenty obszaru roboczego w katalogach katalogowych odczytywanych przez jej stos oraz każdy dokument obszaru roboczego, który nie leży w żadnym katalogu katalogowym — encję Release, jej encję Aggregate i jej encję Manifest zapisane obok katalogów. Dokument obszaru roboczego w katalogu katalogowym odczytywanym tylko przez inne encje Releases nie należy do jej odpowiedzi: nie jest wymieniany, rozwiązywany ani proponowany. Dzięki temu warianty jednej encji, przechowywane obok siebie dla różnych encji Releases, nie są ze sobą mylone.

  • Lista. Wskazanie encji Release powoduje wymienienie encji, które widzi ta encja Release. Wymieniane encje Features to te, które deklarują katalogi katalogowe tej encji Release, a dokument obszaru roboczego w katalogu katalogowym odczytywanym tylko przez inne encje Releases jest pomijany — obszar roboczy przechowujący wariant jednej encji dla każdej encji Release wymienia więc ten jeden wariant, z którym kompiluje się dana encja Release, a nie wszystkie warianty obok siebie. Dokument, który nie leży w żadnym katalogu katalogowym, na przykład encja Release, jej encja Aggregate i jej encja Manifest zapisane obok katalogów, należy do listy każdej encji Release.
  • Wyszukiwanie po nazwie. Wskazanie encji Release powoduje rozwiązanie nazwy przez katalogi katalogowe tej encji Release, więc nazwa deklarowana przez kilka wariantów jest rozwiązywana do wariantu, z którym kompiluje się dana encja Release. Nazwa, której jej katalogi nie rozwiązują, jest odrzucana z wyjaśnieniem wskazującym wpis tej encji Release w workspace.releases, ponieważ to ten wpis odczytało wyszukiwanie. Odwołanie do rejestru nie przyjmuje encji Release i jest odrzucane, jeśli zostanie z nią podane: jest odczytywane z rejestru, który je publikuje, niezależnie od wskazanej encji Release.
  • Podpowiedź i przejście do definicji. Gdy wskazano encję Release, odwołanie pod kursorem jest najpierw rozwiązywane przez katalogi katalogowe tej encji Release, w kolejności podanej w konfiguracji obszaru roboczego — jest to to samo rozwiązywanie, które wykonuje wyszukiwanie po nazwie w kategoriach tej encji Release — więc wyświetlana encja i otwierany dokument to wariant, do którego rozwiązują je te katalogi, nawet jeśli dokument obszaru roboczego w innym miejscu deklaruje tę samą nazwę. Dopiero gdy żaden dokument w tych katalogach na nie nie odpowiada, przeszukiwane są dokumenty obszaru roboczego obejmowane przez tę encję Release. Gdy nie wskazano żadnej, kolejność jest odwrotna: najpierw przeszukiwane są dokumenty obszaru roboczego, więc odwołanie, na które odpowiada dokument obszaru roboczego, zachowuje tę odpowiedź, a własne catalog_dirs obszaru roboczego są sprawdzane tylko wtedy, gdy żaden dokument nie deklaruje tej nazwy — dzięki temu znajdowana jest encja, którą przechowuje wyłącznie skonfigurowany katalog katalogowy, w tym katalog spoza drzewa obszaru roboczego. Jeśli edytor przechowuje niezapisaną kopię dokumentu, do którego rozwiązują katalogi encji Release, i ta kopia nadal deklaruje nazwę, odpowiedź jest odczytywana z kopii, więc pozycja wskazuje wiersz widoczny w edytorze.
  • Uzupełnianie. Gdy wskazano encję Release, proponowane są nazwy deklarowane przez dokumenty obszaru roboczego obejmowane przez tę encję Release, wraz z encjami Components i Features deklarowanymi przez katalogi katalogowe tej encji Release.
  • Odwołania i implementacje. Gdy wskazano encję Release, lokalizacja w dokumencie obszaru roboczego, którego ta encja Release nie obejmuje, nie jest zgłaszana, więc wariant przechowywany dla innej encji Release nigdy nie jest wymieniany jako odwołanie ani implementacja dla tej.
  • Co można dołączyć do węzła grafu. aggrega/attachCandidates skierowane do węzła grafu encji Release zawsze odpowiada w kategoriach tej encji Release — zobacz Co mówi odpowiedź z kandydatami do dołączenia.

Gdy nie wskazano żadnej, odpowiedź opiera się na własnych katalogach katalogowych obszaru roboczego, jak opisuje powyższy akapit.

Sięganie do rejestru i zapisywanie

Większość opisanych tu żądań odpowiada na podstawie obszaru roboczego i tego, co jest już w pamięci podręcznej, i niczego nie zapisuje. Kilka wymienionych robi więcej, a dzielą się one wzdłuż dwóch niezależnych osi: do czego żądanie sięga i jak daleko sięga to, co zmienia.

Żądania, które sięgają do rejestru, dzielą się na te, które czytają, i te, które publikują. aggrega/resolveDependencies pobiera to, czego potrzebuje encja Release, a aggrega/build dołącza do niego wtedy — i tylko wtedy — gdy jego pole autoPull każe mu najpierw rozwiązać zależności; w takim przypadku sięga do rejestru i zapisuje plik blokady przed renderowaniem; aggrega/registryUpdate przechodzi przez każdy skonfigurowany rejestr, aby odbudować lokalny indeks wyszukiwania; aggrega/pluginAdd przeszukuje skonfigurowany rejestr w poszukiwaniu wtyczki wskazanej w żądaniu i odczytuje jej opublikowane wersje, aby przypiąć jedną z nich; aggrega/registryAdd pyta rejestr, który rejestruje, o politykę zaufania, którą ten rejestr ogłasza, chyba że żądanie rezygnuje z pobrania lub dostarcza własną politykę, a aggrega/configInit pyta o to samo rejestr, który inicjuje; aggrega/explainError pozyskuje pakiet dokumentacji, z którego odczytuje omówienie danego stanu, jednorazowo, jeśli pamięć podręczna współdzielona przez wszystkie projekty na maszynie nie zawiera kopii, którą przepuszcza własna weryfikacja podpisu obszaru roboczego — zob. aggrega explain; aggrega/scaffoldEntity z wysłanym example lub list pozyskuje ten sam pakiet na tych samych warunkach, a przy zapisie umieszcza następnie przykład w nowym katalogu obszaru roboczego; aggrega/import pobiera importer podstawowy z domyślnego rejestru obszaru roboczego, jednorazowo, jeśli maszyna jeszcze go nie ma, a w obszarze roboczym, który nie wskazuje żadnego folderu katalogu, także opublikowaną migawkę katalogu, którą odczytuje — zob. Co mówi odpowiedź na import; a aggrega/entityDefinition odczytuje encję wskazaną przez odwołanie do rejestru, gdy zostanie ono przesłane jako name, niczego nie zapisując. aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts i aggrega/deprecateArtifact zapisują do rejestru — bajty, podpis lub znacznik wycofania. Żądanie sięga do rejestru tylko wtedy, gdy zostało wysłane w tym celu: listing podaje to, co przypina konfiguracja, wyszukiwanie czyta migawkę offline, a publikacja zlecona z dryRun oblicza, co by wysłała, i z nikim się nie łączy.

Zasada dotyczy tego, kiedy operacja jest wykonywana, a nie tego, która powierzchnia ją wykonuje. Operacja, która pobiera lub zapisuje, jest wykonywana, ponieważ wskazało ją żądanie, i nigdy jako efekt uboczny walidacji dokumentu, inspekcji grafu czy listowania encji obszaru roboczego. Dlatego edytor, który waliduje przy każdym naciśnięciu klawisza, nie sięga do sieci i nie przepisuje pliku blokady, natomiast akcja „rozwiąż zależności” klikana przez użytkownika robi dokładnie to samo, co aggrega pull — to samo rozwiązywanie za obiema powierzchniami, zapisujące identyczny bajt w bajt plik blokady i wypełniające tę samą pamięć podręczną artefaktów.

Nic nie jest pobierane przez pytanie. Nikt nie obserwuje tego strumienia, więc tożsamość jest ustalana z dostarczonego lub otoczeniowego źródła poświadczeń, a nigdy przez zapytanie. Tam, gdzie polecenie w terminalu zadałoby pytanie człowiekowi — rejestr wymagający poświadczeń, możliwość obsługiwana przez więcej niż jedną wtyczkę dostawcy, tekst, który ma zawierać wycofanie — żądanie kończy się niepowodzeniem z komunikatem wskazującym, co należy dostarczyć, zamiast blokować się w oczekiwaniu na odpowiedź, która nigdy nie nadejdzie. Odmowa pozostawia obszar roboczy dokładnie w takim stanie, w jakim był: nie jest zapisywany plik blokady ani nie pozostaje częściowy zapis, a publikacja, która nie mogła ustalić poświadczenia, odmawia, zanim jakiekolwiek bajty dotrą do rejestru.

Niektóre zmiany sięgają poza ten obszar roboczy, a odpowiedź mówi które

Żądanie wskazuje jeden obszar roboczy, więc odpowiedź, która nic nie mówi o własnym zasięgu, odczytuje się jako dotyczącą tego obszaru roboczego. W przypadku kilku z tych żądań takie odczytanie byłoby błędne, dlatego każde z nich niesie swój zakres, a klient powinien go pokazać przed podjęciem działań na podstawie wyniku.

Publikowanie, podpisywanie i wycofywanie sięgają całkowicie poza maszynę, co jest najszerszym zasięgiem spośród wszystkiego, co tu opisano. Pozostałe zapisy poniżej zmieniają to, co rozwiązuje ta maszyna; te zmieniają to, co rozwiązuje każdy, kto korzysta z tego rejestru. Opublikowane bajty są tym, co otrzymuje każdy konsument tego rejestru, a ponowne opublikowanie innej treści pod tym samym tagiem jest odrzucane, a nie oferowane, więc żadne żądanie tutaj nie cofa publikacji — rozwiązaniem jest opublikowanie nowej wersji. Podpis i znacznik wycofania są dołączane jako elementy równorzędne artefaktu, a nie zastępują go, więc same bajty pozostają nietknięte; ale każdy, kto pobierze artefakt później, pobiera także je, a żadnego z nich nie można odwołać u kogoś, kto już go ma. Wycofanie najłatwiej z tych trzech źle odczytać: wersję nadal można pobrać, natomiast retrakcja, której ufa obszar roboczy, wyłącza ją z tego, co wybierze tam rozwiązywanie.

Podpisywanie korzysta z poświadczeń i warto wiedzieć, skąd one pochodzą, zanim podłączy się klienta. Podpisywanie bezkluczowe ustala token tożsamości, w kolejności: z identityToken w żądaniu, następnie z AGGREGA_IDENTITY_TOKEN w środowisku demona, następnie z otoczeniowego punktu końcowego OIDC GitHub Actions, jeśli jest osiągalny, a na końcu z SIGSTORE_ID_TOKEN. Gdy żadne z nich nie daje tokenu, operacja odmawia i wskazuje, co należy wysłać; nigdy nie otwiera przeglądarki, ponieważ nie ma nikogo, kto by na nią patrzył. Podpisywanie kluczem jest alternatywą offline, a żądanie nie wskazuje ścieżki klucza: to, co żądanie odczytuje, znajduje się wewnątrz wskazanego obszaru roboczego, a klucz prywatny nigdy nie jest przechowywany w obszarze roboczym, więc klucz pochodzi zamiast tego z bloku signing: własnej konfiguracji tego obszaru roboczego. Zob. aggrega sign, aby poznać oba tryby podpisywania i to, z czym każdy z nich się łączy.

Każda z czterech odpowiedzi zawiera reach, w którym znajduje się registries — każdy host rejestru, do którego zwróciło się wywołanie, każdy wymieniony raz, w kolejności pierwszego zwrócenia się, więc partia podpisów lub plik partii, którego odwołania obejmują kilka rejestrów, wymienia każdy z nich — oraz beyondThisMachine, wyprowadzane z tego, co wywołanie faktycznie dołączyło, a nie z tego, o co prosiło: ma wartość true dokładnie wtedy, gdy przesłało treść lub dołączyło podpis, datę publikacji albo znacznik wycofania, a false dla przebiegu próbnego i dla wywołania, które zastało już wszystko, co by dołączyło — publikacji uruchomionej ponownie na wersji, która jest już kompletna, lub partii podpisów, w której każde odwołanie miało już podpis przechodzący weryfikację. Przebieg próbny nadal wskazuje miejsce docelowe, do którego by się zwrócił. Należy je pokazać przed podjęciem działań na podstawie wyniku.

Rejestrowanie lub usuwanie rejestru domyślnie zapisuje konfigurację współdzieloną przez wszystkie obszary robocze na maszynie. Rejestr i tożsamości, którym się w nim ufa, są zwykle takie same niezależnie od miejsca pracy, więc to tam trafia wpis, chyba że żądanie wyśle workspace: true. Konsekwencję warto powiedzieć wprost: aggrega/registryAdd i aggrega/registryRemove zmieniają to, przez co rozwiązuje każdy projekt na tej maszynie, łącznie z projektami, których nikt w tej sesji nie wskazał. Obie odpowiedzi zawierają scope z zapisanym configFile oraz machineWide, które mówi, czy jest to plik współdzielony. Usunięcie jest groźniejsze z tych dwóch, ponieważ ponowne dodanie nie jest tym samym aktem — przypięta polityka zaufania przepada, a późniejsza rejestracja przypina to, co rejestr ogłasza w danym momencie.

Inicjowanie konfiguracji domyślnie zapisuje ten sam współdzielony plik, i z tego samego powodu. aggrega/configInit rejestruje rejestr i jego politykę zaufania, co jest narzędziem obejmującym całą maszynę, więc bez nadpisania zapisuje konfigurację, przez którą rozwiązuje każdy projekt na maszynie — i jednorazowo sięga do tego rejestru, aby odczytać ogłaszaną przez niego politykę. Jego odpowiedź zawiera tę samą parę scope co obie metody rejestru. Różni się od nich w jednym aspekcie, na którym warto polegać: odmawia zamiast nadpisywać istniejący plik konfiguracji, więc nie może zastąpić konfiguracji, z której ktoś korzysta, chyba że żądanie wyśle force. Zamrażanie jest przypadkiem odwrotnym: aggrega/configCapture w ogóle nie przyjmuje nadpisania, zawsze zapisuje własny plik konfiguracji projektu i nie sięga do żadnego rejestru, więc nic z tego, co robi, nie jest widoczne dla innego projektu. Zob. Co pozostawia zapis konfiguracji.

🔴 Dodanie lub usunięcie pluginu rozszerzającego polecenia domyślnie zapisuje ten sam współdzielony plik i to właśnie ten przypadek należy przeczytać uważnie. aggrega/pluginAdd i aggrega/pluginRemove przyjmują type, a typ decyduje, dokąd trafia zapis, gdy nie wysłano żadnego nadpisania. Wpis provider, governance, linter lub importer kształtuje build jednego projektu, więc trafia do własnej konfiguracji tego projektu. Wpis cli to narzędzie obejmujące całą maszynę, dlatego dodanie typu cli, które nie wskazuje ani global, ani workspace, rejestruje polecenie w globalnym pliku konfiguracji, przez który rozwiązuje zależności każdy obszar roboczy na tej maszynie — polecenie staje się poleceniem najwyższego poziomu aggrega dla każdego projektu na tej maszynie, w tym projektów, których nikt w tej sesji nie wskazał, a jego wycofanie jest osobnym usunięciem, a nie cofnięciem. Aby zachować je lokalnie, należy wysłać workspace: true. Obie odpowiedzi zawierają scope z zapisanym plikiem configFile oraz machineWide, które mówi, czy jest to plik współdzielony, wyprowadzone z pliku, na który rozwiązał się zapis. Dodanie sięga też do przeszukiwanego rejestru, więc leży jednocześnie na obu osiach. Zob. Co mówi zmiana pluginu.

Pozostałe dwa żądania dotyczące pluginów zapisują tylko wewnątrz obszaru roboczego. aggrega/pluginSync zapisuje plik encji Plugin wskazany w żądaniu, a aggrega/pluginGenCatalog zapisuje wygenerowane encje w katalogu outputDir wskazanym w żądaniu — oba wewnątrz obszaru roboczego wskazanego w żądaniu, oba odrzucają miejsce docelowe, które jest bezwzględne lub rozwiązuje się poza nim, i żaden nie jest widoczny dla innego projektu. aggrega/pluginGenCatalog odczytuje swój moduł i nakładkę stamtąd, skąd je wybrano, co nie poszerza miejsca, w którym zapisuje: oba są rozwiązywane według różnych reguł, więc generowanie może odczytać moduł zbudowany gdziekolwiek, a tworzone encje i tak trafiają do obszaru roboczego. aggrega/pluginGenCatalog z dryRun nie zapisuje niczego i zamiast tego zwraca treść.

Przypięcie encji również zapisuje tylko wewnątrz obszaru roboczego i sięga do hostów wskazanych przez jej źródła. aggrega/pin zapisuje entity.lock obok encji wskazanej w żądaniu, czyli w ścieżce wewnątrz obszaru roboczego, i wypełnia pamięć podręczną treści obszaru roboczego pobranymi źródłami; nic, co zapisuje, nie jest widoczne dla innego projektu. Sięga na zewnątrz, aby rozwiązać każde zdalne źródło wskazane przez encję — repozytorium chartów, host Git, URL — co jest tym samym zasięgiem, jaki ma aggrega/resolveDependencies dla źródeł konsumowanych przez encję Release. aggrega/resolveDependencies i aggrega/publishEntity z wysłanym pinSources wykonują ten sam krok, więc każde z nich również zapisuje obok przypinanych encji; publikacja, która przypina, sięga zatem zarówno do obszaru roboczego, jak i do rejestru. Publikacja, która nie przypina, nie zapisuje niczego obok encji, a mimo to sięga do tych hostów: porównanie locka z tym, co zapisałby krok, oznacza pobranie w całości każdego zdalnego źródła, które encja wypisuje.

Instalowanie umiejętności asystenta pozostaje w obszarze roboczym, chyba że żądanie wyśle global. aggrega/skillsInstall zapisuje folder umiejętności projektu każdego wskazanego asystenta w obszarze roboczym wskazanym w żądaniu i nic, co tam zapisze, nie jest widoczne dla innego projektu; scope w jego odpowiedzi zawiera machineWide równe false. Z global: true zapisuje zamiast tego folder użytkownika każdego asystenta w katalogu domowym, który ten asystent czyta w każdym projekcie na maszynie, a machineWide ma wartość true. W obu przypadkach nie łączy się z żadnym rejestrem ani z siecią.

Usunięcie zapisanego poświadczenia sięga szerzej niż cokolwiek innego tutaj, co zatrzymuje się na tej maszynie. aggrega/logout zmienia magazyn poświadczeń, a ten magazyn jest współdzielony nie tylko przez każdy projekt na maszynie, ale też przez każde inne narzędzie uwierzytelniające się w tych samych rejestrach — więc poświadczenie usunięte w sesji znika dla nich wszystkich, a aggrega/registryList zgłosi jego brak również w każdym innym obszarze roboczym. Odpowiedź zawiera scope z machineWide, które zawsze ma wartość true: ten magazyn nie ma formy ograniczonej do obszaru roboczego, na którą mógłby się rozwiązać, więc nie ma nadpisania do wysłania ani niczego, na co żądanie mogłoby się zdecydować. scope celowo nie wskazuje żadnego pliku, w przeciwieństwie do opisanych wyżej zapisów konfiguracji. Magazyn deleguje do dowolnego pomocnika poświadczeń lub pęku kluczy systemu operacyjnego skonfigurowanego na maszynie, więc usunięcie często obsługuje coś, co w ogóle nie jest plikiem, a wskazanie ścieżki kierowałoby do lokalizacji, której usunięcie niekoniecznie dotknęło.

Usunięcie nie jest odwrotnością uwierzytelnienia i klient nie powinien go tak przedstawiać. Ten interfejs usuwa poświadczenie, ale go nie pozyskuje: odzyskanie poświadczenia oznacza ponowne uwierzytelnienie za pomocą aggrega login w terminalu, ponieważ zapisanie go wymaga sekretu wpisanego przez człowieka, a nikt nie obserwuje tego strumienia. Dlatego oferowane przez klienta „wylogowanie” jest stąd jednokierunkowe. To, co rozdziela te dwie operacje, to czy operacja musi uzyskać coś od tego, kto nią steruje — usunięcie niesie swoją jedyną wartość w żądaniu, a pozyskanie poświadczenia nie — a nie to, czy uczestniczy w niej człowiek, skoro człowiek wybrał obie.

Odzyskiwanie miejsca w pamięci podręcznej również sięga poza obszar roboczy. Magazyny skompilowanych modułów i opisów pluginów są współdzielone przez każdy projekt na maszynie, więc aggrega/cachePrune, aggrega/cacheEvict i aggrega/cacheClear mogą usunąć treść, od której zależy inny projekt. Każde usunięcie niesie reach klasy, z której pochodzi, a każda odpowiedź zawiera scope.machineWideClasses. aggrega/cacheStatus podaje ten sam zasięg dla każdej klasy, mimo że niczego nie zmienia, ponieważ klient decydujący o odzyskaniu miejsca potrzebuje go zanim zadziała.

Odświeżanie indeksu wyszukiwania działa odwrotnie. aggrega/registryUpdate sięga do każdego skonfigurowanego rejestru, a to, co zapisuje, trafia do własnego skonfigurowanego katalogu pamięci podręcznej tego obszaru roboczego — więc nie zmienia niczego, przez co rozwiązuje zależności inny projekt. indexRoot w odpowiedzi wskazuje ten katalog.

Częściowe odświeżenie zwraca odpowiedź zamiast błędu. Żądanie wskazujące jeden rejestr, którego odświeżenie się nie powiodło, jest błędem, ponieważ nie ma odpowiedzi do udzielenia. Żądanie odświeżające każdy skonfigurowany rejestr kończy się powodzeniem, nawet jeśli niektóre z nich lub wszystkie zawiodły: odświeżone zostały zindeksowane i zapisane, failed wymienia pozostałe, a każdy host niesie własny błąd. Należy odczytywać failed, a nie obecność błędu.

To, czy rejestr był osiągalny, jest kluczem, a nie interpretacją komunikatu. Host, który zawiódł, niesie unreachable: true tam, gdzie rejestru nigdy nie osiągnięto — jego nazwa się nie rozwiązała, połączenie z nim zostało odrzucone lub nie dało się go otworzyć albo nie udało się nawiązać z nim bezpiecznego połączenia — a odmowa żądania wskazującego jeden rejestr niesie ten sam klucz w swoim data. Rejestr, który osiągnięto i który zawiódł, z listingiem, który się powtarzał, lub statusem błędu, nie niesie żadnego z nich, a jego error lub komunikat odmowy mówi, co odpowiedział. Klucz jest odczytywany z samej awarii, więc nie zależy od tego, jak resolver tej maszyny formułuje awarię, i jest ustawiany tylko tam, gdzie awaria pokazuje, że rejestru nigdy nie osiągnięto: awaria, która nie pokazuje niczego w żadną stronę, na przykład upływ limitu czasu bez zapisu, który krok przerwał, jest zgłaszana bez niego. Rejestr należy oznaczać jako nieosiągnięty na podstawie klucza, a błąd pokazywać jako przyczynę.

Wiersz poleceń zgłasza ten sam przebieg jako niezerowy kod wyjścia, a to, kim jest odbiorca, decyduje, ile ten kod jest wart. Dla osoby przy terminalu nie jest to pełny obraz: aggrega registry update wypisuje, ile z wybranych rejestrów zindeksował, co znalazł w każdym z nich, których nie zindeksował i gdzie zapisano indeks — więc podsumowanie mówi, co się stało, a kod wyjścia mówi tylko, czy całość się powiodła. Dla skryptu jest to pełny obraz, ponieważ to polecenie nie oferuje trybu wyjścia strukturalnego, więc jego kod wyjścia jest jedynym dostępnym werdyktem czytelnym maszynowo. Dlatego te dwa interfejsy odpowiadają na ten sam częściowy przebieg inaczej i oba mają rację: ten przekazuje wywołującemu strukturalnie failed i kończy się powodzeniem, a wiersz poleceń ma do wykorzystania jeden bit i wykorzystuje go na „czy pominięto jakikolwiek rejestr”.

Obserwowanie długiej operacji

Większość żądań odpowiada na podstawie tego, co jest już na dysku, i odpowiada od razu. Kilka z nich najpierw wykonuje rzeczywistą pracę — rozwiązuje zależności encji Release, przypina jej zewnętrzne wejścia, publikuje, podpisuje, wycofuje — a wywołujący czeka. Takie żądania raportują, co robią, w trakcie pracy, a raportowanie włącza się osobno dla każdego żądania.

Włączenie wymaga dwóch kroków, w tej kolejności.

  1. Zadeklaruj możliwość podczas uzgadniania połączenia i poczekaj na odpowiedź. Należy wysłać capabilities.window.workDoneProgress: true w aggrega/initialize. Do czasu nadejścia odpowiedzi nie należy wysyłać niczego innego: żądania są obsługiwane współbieżnie, więc żądanie zapisane przed odpowiedzią na uzgadnianie może działać równolegle z uzgadnianiem, które miało je wynegocjować. Każdy klient i tak jest zobowiązany przez protokół do zachowania tej kolejności; to kolejna rzecz, która od niej zależy.
  2. Umieść token w parametrach żądania. Należy dodać workDoneToken do parametrów żądania, o którym mają przychodzić raporty. Wartość wybiera klient — ciąg znaków lub liczba — i to ona wiąże powiadomienia z danym wywołaniem. Dla każdego wywołania należy utworzyć nowy token.

Powiadomienie. Każde z nich to $/progress z params.token ustawionym na token klienta i params.value niosącym jeden ładunek:

value.kindzawierakiedy
begintitle — co się dzieje, we frazie, którą można pokazać czytelnikowiraz, gdy praca się zaczyna
reportmessage — jeden wiersz własnej relacji operacji o sobiedowolną liczbę razy, w miarę jak operacja je zapisuje
endnic poza rodzajemraz, gdy praca się kończy

Należy korelować po tokenie, nigdy po identyfikatorze żądania. Powiadomienie nie zawiera identyfikatora — nie jest odpowiedzią na nic — a token jest jedynym jego elementem wskazującym z powrotem na wywołanie. Jest to zamierzone: w wielu klientach identyfikator żądania należy do warstwy transportowej i nigdy nie dociera do kodu, który wykonał wywołanie, natomiast token jest wartością, którą ten kod już ma.

report zawiera własny tekst kompilatora. Komunikat to jeden wiersz zapisany przez operację w trakcie pracy, przekazany z usuniętymi otaczającymi białymi znakami i bez żadnych innych zmian — bez przeredagowania, streszczania czy ponownego składania — a wiersz zapisany przez operację jako pusty jest pomijany, zamiast być raportowany jako pusty komunikat. Klient pokazuje więc to, co otrzymuje, bez zmian. To ta sama właściwość, którą mają diagnostyki samej odpowiedzi: jeden warunek zachowuje jedno sformułowanie niezależnie od tego, ile powierzchni go raportuje.

Krok, na który czeka operacja, to również report. Gdy operacja wchodzi w krok, na który czeka — odczyt rejestru, pobranie artefaktu, kompilację wtyczki — report niesie nazwę kroku, tymi samymi słowami, które wiersz poleceń pokazuje dla tego kroku obok wskaźnika postępu. Raportowane są tylko kroki, w które operacja weszła między begin a end.

Jeden wiersz wyjścia to jeden report. Operacja, która zapisuje kilka wierszy naraz, generuje jedno powiadomienie na wiersz, a wiersz zapisywany przez operację we fragmentach jest raportowany dopiero po ukończeniu — komunikat nigdy nie jest więc połową zdania.

Nie ma ułamka ani procentu i nie jest to brak czekający na uzupełnienie. Operacje, które tu raportują, przetwarzają zbiór, którego rozmiar nie jest znany w chwili rozpoczęcia pracy — ile odwołań przechodzi rozwiązywanie, ile warstw wysyła publikacja — więc każdy ułamek byłby zmyślony. Należy wyświetlić nieokreślony wskaźnik i pokazać najnowszy message.

Ramki przychodzą przed odpowiedzią i nigdy po niej. begin przychodzi dopiero wtedy, gdy praca faktycznie się rozpoczęła, więc żądanie odrzucone z powodu parametrów — ścieżki bezwzględnej, brakującego wymaganego pola — nie generuje żadnego powiadomienia, tylko swój błąd. end przychodzi przed odpowiedzią, a to, czy operacja się powiodła, jest zawarte w odpowiedzi, a nie powtarzane w end.

Zatrzymanie pracy to osobne powiadomienie. Należy wysłać $/cancelRequest z identyfikatorem, pod którym wysłano żądanie. Token nie odgrywa roli w anulowaniu, a anulowanie nie wycofuje już wysłanych ramek.

Które żądania raportują i czego oczekiwać od pozostałych

Raportują dokładnie te: aggrega/resolveDependencies, aggrega/pin, aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact.

Dwie rzeczy są prawdziwe dla każdego z nich i obie są powodem, dla którego znajduje się na liście: sięga do rejestru lub zdalnego adresu URL w imieniu klienta, więc czas jego trwania zależy od czegoś spoza maszyny; oraz już w trakcie działania zapisuje własną relację o sobie — tę, którą czyta osoba obserwująca terminal. Raportowanie przekazuje więc tę samą relację, a nie drugą, złożoną specjalnie do transmisji, i nic w działaniu operacji nie musiało się zmienić, aby ją wytworzyć.

Każde inne żądanie przyjmuje token i nic nie wysyła. Wysłanie tokenu jest nieszkodliwe, a nie jest błędem: zostaje przyjęty, żadne powiadomienie nie przychodzi, a odpowiedź jest dokładnie taka sama jak bez niego. Klient może więc dołączyć token do czegokolwiek i po prostu nic nie wyświetlać, gdy nic nie przychodzi.

🔴 Nie należy odczytywać ciszy jako „to jest natychmiastowe”. Większość pozostałych rzeczywiście odpowiada na podstawie tego, co jest już na dysku — walidacja, podpowiedź, uzupełnianie, graf, lista pamięci podręcznej, odczyt konfiguracji — ale nie wszystkie: odświeżenie indeksu rejestru, dodanie pluginu, kontrola przed publikacją oraz pierwsze rozwinięcie kodu na maszynie bez dokumentacji, którą obszar roboczy może odczytać, sięgają do rejestru, a kompilacja encji Release to rzeczywista praca. Trwają tyle, ile trwają, i obecnie niczego nie raportują. Dla każdego żądania, na które klient jest gotów czekać, należy pokazywać nieokreślony wskaźnik, a powiadomienia traktować jako szczegóły dostępne wtedy, gdy są, a nie jako sygnał, że praca trwa.

Dwa odrzucenia

Oba są błędami invalid-params i oba wskazują, co zrobić, ponieważ token, który po cichu nic by nie robił, zostawiłby klienta w oczekiwaniu na strumień, który nigdy nie nadejdzie.

  • Token z sesji, która nie zadeklarowała możliwości window.workDoneProgress, jest odrzucany, z podaniem możliwości do zadeklarowania. Należy ją zadeklarować podczas uzgadniania połączenia albo pominąć token.
  • Token, który nie jest ani ciągiem znaków, ani liczbą, jest odrzucany, z podaniem obu dopuszczalnych postaci. Brak tokenu oraz jawne null nie są odrzucane — oba oznaczają, że nie zażądano raportu.

Świadomość pliku blokady

Demon sprawdza plik blokady pod kątem dryfu przy każdym aggrega/irGraph, względem encji Release wskazanej w tym żądaniu, i zgłasza dryf jako ostrzeżenie nieblokujące. Ostrzeżenie wskazuje polecenie, które przepisuje ten plik blokady z daną encją Release, zapisane tak, jak wysłało je żądanie — aggrega pull --release, a po nim wysłana wartość release, czyli tak, jak wpisuje się je w terminalu w katalogu głównym obszaru roboczego. aggrega/irGraph wymaga obecności pliku blokady. Nie ma osobnego sprawdzenia przy uruchomieniu: żądanie określa, której encji Release dotyczy, więc werdykt jest obliczany dla tej encji Release w chwili, gdy się o niego prosi, a nie raz, dla jednej encji Release wybranej z góry.

Ostrzeżenie o dryfie znika wraz z plikiem blokady. Ostrzeżenie jest publikowane dla pliku blokady, względem którego zostało zgłoszone, a plik blokady, którego już nie ma, nie zawiera przypięć, które mogłyby dryfować — polecenie wskazane w ostrzeżeniu zapisałoby nowy plik, a nie naprawiło stary. Dlatego każde żądanie, które stwierdzi brak pliku blokady, wycofuje ostrzeżenie, zanim odmówi z błędem braku pliku blokady: aggrega/irGraph, aggrega/releaseClosure, aggrega/build, aggrega/buildPreview, aggrega/attachCandidates i aggrega/attachmentContainer zapytane o węzeł grafu oraz aggrega/connectionAtPosition. Wycofanie przychodzi jako powiadomienie aggrega/publishDiagnostics dla pliku blokady z pustą listą, przed odmową. Pochodzi od tego z tych żądań, które pierwsze dowie się o usunięciu, więc klient, który zgłosi usunięcie, a potem zapyta o cokolwiek dotyczącego tej encji Release, ma ostrzeżenie wyczyszczone bez konieczności pytania konkretnie o graf. Plik blokady, który nadal istnieje i nadal dryfuje, zachowuje ostrzeżenie przez każde z tych żądań. aggrega/invalidate wskazujące plik blokady usuwa to, co demon dla niego przechowuje, ale niczego nie wysyła; o stanie informuje klienta dopiero następne żądanie. Natomiast plik blokady, którego demon nie może nawet zbadać — na przykład taki, którego katalogu nie wolno mu odczytać — niczego nie wycofuje, ponieważ może nadal istnieć, a ostrzeżenie może nadal być prawdziwe.

aggrega/build i aggrega/buildPreview również go wymagają i rozliczają z niego encję Release, zamiast ostrzegać — renderują w trybie powierzchni, która emituje artefakt, więc plik blokady, który nie odpowiada już temu, do czego rozwiązuje się encja Release, zatrzymuje je tam, gdzie inspekcja jedynie by ostrzegła. Encja Release bez pliku blokady jest odrzucana z błędem braku pliku blokady. Wyjątkiem jest kompilacja, której pole autoPull każe najpierw rozwiązać zależności: taka kompilacja zapisuje plik blokady, a następnie renderuje względem tego, co zapisała, a plik blokady powstały w ten sposób nie jest sprawdzany pod kątem dryfu drugi raz, ponieważ rozwiązywanie, które go zapisało, przeprowadziło to samo sprawdzenie przed zapisem i nie zapisuje pliku blokady, który to sprawdzenie odrzuca.

Plik blokady, który istnieje, ale nie zawiera skrótu dla pluginu, nie zatrzymuje grafu — zatrzymuje go brak pliku blokady. To dwa różne warunki i tylko drugi powoduje odmowę. aggrega/irGraph nie rozlicza rozwiązywanych bajtów z zapisanymi skrótami: przypięcie, którego nie może zweryfikować, jest zgłaszane, a nie odrzucane, a graf jest rysowany z ustaleniem w panelu Problems, ponieważ edytor, który odmawia narysowania grafu, nie zostawia czytelnikowi niczego, podczas gdy zgłoszenie daje mu coś, na co może zareagować. W innych miejscach plugin również działa, z ostrzeżeniem, że nic nie sprawdziło jego bajtów. aggrega/irGraph odrzuca brak pliku blokady: zatrzymuje się, zanim cokolwiek rozwiąże, i odpowiada błędem braku pliku blokady, wskazując szukany plik blokady i encję Release, dzięki czemu klient może bezpośrednio zaproponować aggrega pull --release <release> — albo wysłać aggrega/resolveDependencies dla tej encji Release i zapisać plik blokady bez opuszczania sesji. Rozdzielenie tych dwóch przypadków ma znaczenie, ponieważ narysowany graf to obraz, na podstawie którego czytelnik potem wnioskuje, a graf zbudowany z bajtów, których nic nie sprawdziło, wygląda dokładnie tak samo jak sprawdzony, a ustalenie znajduje się tam, gdzie czytelnik nie patrzy. Graf nie jest więc werdyktem co do stojących za nim bajtów — to aggrega/build i aggrega/buildPreview są powierzchniami, które rozliczają encję Release z zapisanych skrótów i zatrzymują się tam, gdzie inspekcja tylko zgłasza.

aggrega/validate, gdy żądanie wskazuje encję Release, odczytuje plik blokady tej encji Release wyłącznie w celu pobrania przypięć i powiadomień o wycofaniu — a dla encji katalogu sprawdzanej jako pojedyncza encja nie odczytuje żadnego, tak jak nie odczytuje go wiersz poleceń. Nie rozlicza uruchamianych pluginów z zapisanymi skrótami i nie odtwarza zestawu dołączeń pluginów transformujących z pliku blokady — waliduje względem konfiguracji obszaru roboczego w jej bieżącym stanie, co edytor musi robić podczas edycji tej konfiguracji. aggrega validate i aggrega build robią jedno i drugie i pozostają rozstrzygającymi powierzchniami dla werdyktu dotyczącego zatwierdzonego obszaru roboczego.

Jego powiadomienia o wycofaniu obejmują oba miejsca, w których rejestrowane jest wycofanie. Znacznik na przypiętym odwołaniu znajduje się w pliku blokady; znacznik na wtyczce dołączonej w roli zwracającej werdykt akceptacji lub odrzucenia — dołączeniu plugins.governance w ir-verdict lub render-verdict albo dołączeniu plugins.linter — znajduje się w rejestrze zaufania wtyczek obok niego, więc walidacja odczytuje oba i wymienia każde wycofane odwołanie i każdą wycofaną wtyczkę jako ostrzeżenie na początku encji Aggregate, w brzmieniu, które wypisuje aggrega build. Powiadomienie nie zmienia żadnego werdyktu. Rejestr zaufania, który istnieje, ale nie można go odczytać, jest zgłaszany jako błąd w miejsce walidacji, a nie odczytywany jako rejestr, który niczego nie odnotowuje. aggrega/releaseClosure zgłasza ten sam zbiór w swoim deprecations.

Gdzie znajduje się plik blokady encji Release

Każda odpowiedź, która wskazuje encję Release, wskazuje także jej plik blokady, więc klient nigdy nie musi sam ustalać ścieżki. aggrega/activeRelease przekazuje go jako lockfile obok release, aggrega/releaseCandidates jako mapę lockfiles obok releases, a błąd braku pliku blokady jako lockfile w swoim data. Za każdym razem jest to plik, który zapisuje aggrega pull --release <release> i odczytuje aggrega build, i plik, którego szuka każde z powyższych żądań — dzięki temu klient obserwujący plik blokady encji Release, aby zauważyć jego zapis, przepisanie lub usunięcie, obserwuje ten plik, o który chodzi demonowi. Plik blokady leży obok swojej encji Release i przyjmuje jej nazwę, w której rozszerzenie .yaml lub .yml zastąpiono .lock; encja Release nazwana z innym rozszerzeniem zachowuje całą nazwę, więc plikiem blokady release.rel jest release.rel.lock. Ścieżkę należy odczytywać z odpowiedzi, a nie składać na podstawie tego opisu — wtedy obie nie mogą się rozejść.

Zewnętrzne odwołania, o które prosi renderowanie

Renderowanie może poprosić o treść spod zdalnego adresu URL — na przykład o schemat wartości wykresu ze zdalnym odwołaniem. Zewnętrzne dane wejściowe są zamrożone dla każdego renderowania, które ten demon wykonuje w odpowiedzi na żądanie, które prosiło jedynie o informację. Odwołanie przypięte w pliku blokady encji Release jest obsługiwane z magazynu adresowanego treścią, co jest odczytem treści już obecnej na dysku, a nie pobieraniem, i przed udostępnieniem jego bajtów jest sprawdzane względem tego, co zapisano w pliku blokady — dzięki temu renderowanie widzi tu to samo, co widzi kompilacja, i zgłasza te same ostrzeżenia, które zgłasza kompilacja. Odwołanie, którego plik blokady nie przypina, jest odrzucane, a nie pobierane: jego pozyskanie wymagałoby sięgnięcia do sieci i zapisania obiektu w magazynie, a sesja nie robi żadnej z tych rzeczy przy żądaniu, które prosiło jedynie o informację. Jest to reguła z sekcji Sięganie do rejestru i zapis widziana od strony renderowania i obowiązuje niezależnie od tego, jak doszło do takiego renderowania.

Wyjątkiem jest żądanie, które służy do przypinania, i jest to ten sam wyjątek, który zawiera już reguła dotycząca rejestru. Od aggrega/resolveDependencies oczekuje się pozyskiwania, więc renderowanie, które wykonuje, aby ustalić, z jakich odwołań korzysta dana encja Release, sięga do sieci i zapisuje to, co przypina — i właśnie dlatego jego wynikiem jest plik blokady, a nie raport. Żadne renderowanie, które żądanie grafu lub kompilacji wykonuje na własny użytek, nie robi niczego z tych rzeczy.

Kompilacja, od której zażądano wcześniejszego rozwiązania zależności, otrzymuje odpowiedź z tego samego renderowania i dlatego renderuje encję Release tylko raz. Rozwiązywanie zależności wyrenderowało już to, czego dotyczy kompilacja, względem właśnie zapisanych przypięć i z tymi samymi bramkami, które uruchamia kompilacja, więc kompilacja przedstawia to renderowanie zamiast wykonywać drugie — a pozyskiwanie nadal należy do rozwiązywania zależności, a nie do kompilacji. W ten sposób wykorzystywane jest tylko renderowanie, które się zakończyło: jeśli rozwiązywanie przypięło zależności, ale nie zdołało dokończyć wykrywania zewnętrznych odwołań, kompilacja renderuje samodzielnie względem przypięć, które zostały zapisane, a nieprzypięte odwołanie jest tam odrzucane i zgłaszane dokładnie tak samo jak w kompilacji, która niczego nie rozwiązywała.

Odrzucenie jest zgłaszane, a nie pochłaniane, ponieważ nic w wyniku nie wskazuje, którego odwołania w nim zabrakło. W przypadku dostawców wbudowanych w ten plik binarny dostawca, który poprosił o odwołanie, zwraca odmowę, więc renderowanie, które natrafiło na odrzucone odwołanie, nie kończy się. Każde odrzucone odwołanie trafia zatem jako osobny wpis na warstwę aggrega-build, wskazując odwołanie i polecenie, które je przypina: aggrega pull --release <release> lub aggrega/resolveDependencies, aby wykonać to samo bez opuszczania sesji. Wpisy te są ostrzeżeniami, a nie odmową — graf jest nadal zwracany, tak samo jak w przypadku opisanego wyżej ostrzeżenia o rozbieżności — i są przypisywane encji Aggregate na początku pliku, ponieważ odwołanie, o które poprosiło renderowanie, nie wskazuje żadnego klucza zapisanego przez autora. Są przesyłane w tej samej publikacji co własne ostrzeżenia renderowania, która zastępuje całą warstwę, więc odwołanie, które następnie zostanie przypięte, przestaje być zgłaszane bez konieczności czyszczenia czegokolwiek. W pełni przypięte renderowanie nie zgłasza w tej kwestii niczego. Kształt każdego wpisu opisano w sekcji Co zawiera wpis diagnostyczny.

W przypadku aggrega/irGraph zależy to od tego, czy etap renderowania w ogóle zostanie uruchomiony. Żądanie grafu pomija renderowanie, chyba że włączy je --build-on-inspect lub nadpisywany przez nie klucz serve.build_on_inspect; gdy to ustawienie jest wyłączone, nic nie prosi o zewnętrzne odwołanie i nie ma czego odrzucać. Jego włączenie sprawia, że do sesji edytora trafiają zarówno własne ostrzeżenia renderowania, jak i te opisane tutaj.

Czym sesja różni się od tego samego zamrożenia w wierszu poleceń. aggrega build również zamraża zewnętrzne dane wejściowe podczas przebiegu próbnego, a nieprzypięte odwołanie zachowuje się tak samo na obu powierzchniach: jest zgłaszane jako wynik wskazujący odwołanie, a renderowanie następnie się zatrzymuje, ponieważ dostawca, który o nie poprosił, zwraca odmowę. Różnica dotyczy ponownego pobierania. W wierszu poleceń przypięte odwołanie, którego zapisana kopia zniknęła, jest pobierane ponownie według zapisanego skrótu; renderowanie odpowiadające na żądanie grafu lub kompilacji niczego nie pobiera ponownie, ponieważ nie sięga do sieci, więc nie może wrócić po przypięte odwołanie, którego magazyn już nie zawiera — a takie odwołanie nie należy do opisanych wyżej odrzuceń, które dotyczą tego, czego plik blokady nie przypina. Odzyskuje się je, prosząc sesję o przypięcie: wymienione wyżej żądania sięgają do sieci i przywracają brakujące bajty. Co przypinanie pobiera i zapisuje, opisano w aggrega pull.

Co mówi uruchomienie, które zostało odrzucone

Żądanie, które odmawia, odpowiada kopertą błędu, a ustalenia poczynione już przez uruchomienie nie są przenoszone w tej kopercie — koperta nie zawiera żadnej treści wyniku. Docierają one tak samo jak w przypadku uruchomienia, które się zakończyło: jako publikacja diagnostyczna w warstwie aggrega-build, opisana w sekcji Co zawiera wpis diagnostyczny. Klient obsługujący odmowę odczytuje więc z koperty, co należy zmienić, a z powierzchni problemów — co uruchomienie wykryło, i żadne z nich nie zastępuje drugiego. Odmowa zgłoszona podczas renderowania jest jedyną odmową, która jest również ustaleniem dotyczącym tego, co napisał autor, więc trafia w oba miejsca, jak opisuje następna sekcja.

Ta publikacja następuje niezależnie od tego, czy uruchomienie dotarło do końca. Uruchomienie zatrzymane w połowie nadal wykryło wszystko przed miejscem zatrzymania, a czytelnik, który utraciłby te ustalenia, musiałby uruchomić je ponownie, aby je zobaczyć — dlatego ostrzeżenia są publikowane na podstawie tego, do czego uruchomienie dotarło, a odmowa jest zwracana później. Jest to ten sam zbiór, z tą samą dokładnością, umieszczony przy tych samych kluczach autorskich: odmowa nie degraduje ustalenia do zdania. Odrzucone odwołania zewnętrzne trafiają do tej samej publikacji, z tego samego powodu i tą samą drogą.

Ogranicza ją to, jak daleko dotarło uruchomienie, a nie to, co warstwa może przenieść. Odmowa z jednego z testów wykonywanych przed uruchomieniem kompilatora — nie udało się rozwiązać domknięcia encji Release, Manifest mapuje typ na recepturę, która go nie implementuje, plik blokady nie odpowiada już temu, do czego rozwiązuje się Release, przypięty wpis w pamięci podręcznej nie odpowiada już zapisanemu dla niego skrótowi i żaden katalog nie zawiera przypiętych bajtów — nie ma ostrzeżeń do opublikowania, ponieważ żadne nie zostały jeszcze zgłoszone. Warstwa nie zawiera wtedy niczego zamiast czegoś nieaktualnego; a uruchomienie, które nie dotarło do wskazania dokumentu, nie publikuje niczego, pozostawiając zawartość powierzchni problemów dokładnie taką, jaka była, zamiast czyścić wpisy, o których niczego się nie dowiedziało.

Odmowa zgłoszona podczas renderowania

Release, którą kompilator odrzuca podczas renderowania — Workload wskazujący slot, którego nie deklaruje jego Component, asercja, która nie przechodzi, szablon, którego nie da się obliczyć, realizacja niespełniająca tego, co musi zapewnić — jest zgłaszana tam, gdzie wskazuje, i słowami kompilatora, w każdym żądaniu, które ją renderuje: aggrega/build, aggrega/buildPreview oraz aggrega/irGraph z włączonym etapem renderowania. Odpowiedzią jest koperta błędu z kodem -32603, której message to odmowa wraz ze wszystkimi przyczynami pod nią, tymi samymi słowami, które wypisuje wiersz poleceń dla tej samej kompilacji: renderowany węzeł, następnie to, co w nim odmówiło, każda przyczyna po tej, którą wyjaśnia — poprzedzone, jeśli odmowa wskazuje zarejestrowany warunek, krótkim kodem tego warunku, tak jak każda odmowa go wskazująca. Jej data wskazuje dokument, na który wskazuje odmowa, jako file, a zakres klucza w nim jako line, column, end_line i end_column, obok code i shortCode warunku; odmowa niewskazująca klucza lub wskazująca klucz, którego dokument nie zawiera, zawiera tylko file, a odmowa niewskazująca żadnego dokumentu wskazuje encję Aggregate tej Release.

Ta sama odmowa jest publikowana w warstwie aggrega-build, w tym dokumencie, przy tym kluczu, jako wpis o ważności error zawierający własny keyPath odmowy i message koperty bez poprzedzającego go krótkiego kodu oraz — jeśli odmowa wskazuje zarejestrowany warunek — code, shortCode i codeDescription tego warunku, przy czym krótki kod jest tam przenoszony we własnym polu. Trafia do tej jednej publikacji, która zawiera ostrzeżenia zgłoszone przez uruchomienie przed zatrzymaniem, więc zastępuje warstwę tak jak one: następne uruchomienie tej Release, które renderuje, publikuje warstwę bez niej, a dokument, w którym się znajdowała, jest publikowany jako pusty, co usuwa ją z powierzchni problemów.

Miejsce, na które wskazuje odmowa, to dokładnie to, co sama odmowa wskazuje, i nic dokładniejszego. Testy encji Workload oceniają dokument wygenerowany przez jej szablon, a szablon może zapisać wiersze, których nie napisał żaden autor — pętlę, warunek, tekst zaimportowany z pliku lub biblioteki — więc wiersz wyrenderowanej encji Workload nie odpowiada wierszowi encji Recipe. Odmowa dotycząca encji Workload jest zatem umieszczana przy kluczu workload encji Recipe, a ścieżki, które wskazuje wewnątrz wyrenderowanego dokumentu, pozostają w jej komunikacie. Nieudana asercja jest umieszczana przy własnym kluczu pod assertions w encji Recipe lub FeatureRecipe, która ją deklaruje; asercja deklarowana przez encję Component lub Feature jest zgłaszana, zanim jakikolwiek dokument jest dostępny do wskazania, i umieszczana przy kluczu kind: encji Aggregate. Odmowa z kroku, który wskazuje dokument, ale nie klucz, jest umieszczana przy kluczu kind: tego dokumentu.

Odmowa łącząca kilka ustaleń jest publikowana ustalenie po ustaleniu. Składanie grafu, na którym pracuje renderowanie, odmawia, podając w jednej odmowie każde wykryte naruszenie — wpis wskazujący cel, któremu nic nie odpowiada, dwa połączenia jednego komponentu z nadanym jednym aliasem — a wiersz poleceń wypisuje każde jako osobną diagnostykę, pod własnym nagłówkiem. Tutaj każde jest osobnym wpisem w warstwie aggrega-build, w dokumencie i przy kluczu, które to ustalenie wskazuje — w encji Release, jeśli zapisała je Release, w encji Aggregate, jeśli zrobił to Aggregate — własnymi słowami i z własnymi kodami. message odpowiedzi zawiera wszystkie ustalenia, a jej data wskazuje, dokąd wskazuje pierwsze z nich.

Wartość, którą autor zadeklarował jako wrażliwą, jest tu ukrywana dokładnie tak, jak ukrywa ją wiersz poleceń. Tekst odmowy to tekst zgłoszony przez kompilator, nic na tej powierzchni go nie przeformułowuje, a kompilator ukrywa zadeklarowaną wartość w miejscu zgłoszenia odmowy — w jej miejscu pojawia się <redacted> — więc ta odpowiedź, ten wpis i terminal przekazują ją tymi samymi słowami; co odmowa mówi o zadeklarowanej wartości opisuje, jak to działa i które odmowy pozostają poza tym.

Nie dotyczy to odmowy z bramki wykonywanej przed renderowaniem. Testy wymienione powyżej odpowiadają tak, jak opisuje Co mówi odrzucony przebieg. Asercja deklarowana przez encję Component lub Feature oraz odmowa dotycząca złożonego grafu znajdują się pomiędzy: każda jest zgłaszana przed renderowaniem, przez każde żądanie rozwiązujące graf encji Release, więc aggrega/irGraph odpowiada nią i publikuje ją jak powyżej również przy wyłączonym etapie renderowania; aggrega/releaseClosure, aggrega/attachCandidates i aggrega/attachmentContainer zapytane o węzeł grafu oraz aggrega/connectionAtPosition odpowiadają na nią tą samą kopertą i niczego nie publikują, ponieważ nie mają własnej powierzchni problemów.

Kody błędów

Odpowiedzi używają standardowych kodów błędów JSON-RPC oraz zakresu na poziomie aplikacji w paśmie 1xxx. Klient edytora może rozgałęziać logikę według kodu bez parsowania komunikatu.

  • 1001 file-not-validated — demon nie przechowuje dla pliku, w jego obecnej postaci, niczego, na podstawie czego żądanie mogłoby otrzymać odpowiedź: brak sparsowanej postaci pliku albo, w przypadku aggrega/diagnostics, brak sparsowanej postaci pliku lub brak czegokolwiek przechowywanego dla pliku, co byłoby odpowiedzią walidacji dla tekstu obecnie przechowywanego przez demona. Należy wysłać dla niego aggrega/validate i zapytać ponownie.
  • 1003 lockfile-absent — encja Release wskazana w żądaniu nie ma pliku lockfile, a żądana operacja go wymaga.
  • 1004 entity-not-resolvable — nazwa nie pasuje do żadnej encji w żadnej warstwie katalogu ani w encji Release wskazanej w żądaniu; albo odwołania do rejestru wysłanego jako nazwa nie udało się odczytać jako encji, a komunikat wskazuje warunek, który wyjaśnia przyczynę; albo plik lockfile encji Release jest dowiązaniem prowadzącym poza przestrzeń roboczą, co zostaje odrzucone, zanim cokolwiek go odczyta, przy czym data wskazuje plik lockfile i encję Release, a komunikat zaczyna się od krótkiego kodu warunku, E0321 — zob. granica przestrzeni roboczej.
  • 1005 shutting-down — demon kończy pracę po powiadomieniu o zamknięciu i odrzuca nowe żądania. Nie należy ponawiać prób wobec tego samego podprocesu.
  • 1006 validation-in-flight — trwa walidacja pliku, która nie zakończyła się w limicie czasu przyznanym przez oczekujące żądanie. Należy wkrótce zapytać ponownie i niczego nie wysyłać.

1002 nie jest przydzielony i pozostaje dostępny dla następnego warunku, który będzie potrzebował kodu.

File-not-validated i validation-in-flight zgłaszają przeciwne stany, a działania, których wymagają, również są przeciwne. File-not-validated oznacza, że demon nie przechowuje dla pliku, w jego obecnej postaci, niczego, na podstawie czego żądanie mogłoby otrzymać odpowiedź — brak sparsowanej postaci pliku albo, w przypadku aggrega/diagnostics, brak sparsowanej postaci pliku lub brak czegokolwiek przechowywanego dla pliku, co byłoby odpowiedzią walidacji dla tekstu obecnie przechowywanego przez demona: należy wysłać aggrega/validate i zapytać ponownie. Walidacja anulowana w trakcie pozostawia plik w tym stanie, ponieważ niczego nie zapisuje, a to, co wcześniejsza walidacja ustaliła na temat innego tekstu, nie jest odpowiedzią dla tekstu obecnie przechowywanego przez demona; wcześniejsza odpowiedź pozostaje ważna, dopóki tekst jest tym, który ona sprawdziła. Ustalenia, które demon wysyła na temat pliku odczytanego przez siebie z dysku — lockfile, który przestał być zgodny, encja Release, która się nie wczytuje — nie są walidacją posiadanego tekstu, więc również nie odpowiadają na to żądanie. W tym stanie można się też znaleźć po wysłaniu w krótkim odstępie dwóch walidacji różnych tekstów, gdy jako pierwsza zakończyła się ta, której tekst demon zachował: żądanie zostaje odrzucone, choć ten tekst został sprawdzony, a ponowna walidacja daje na nie odpowiedź. Jest to sformułowane w kategoriach parsowania, a nie pliku, ponieważ bufor, którego żaden parser nie odczyta, jest dokładnie w tej sytuacji — walidacja się wykonała i zgłosiła to, co znalazła, a nadal nie ma sparsowanej postaci, na podstawie której można odpowiedzieć. Validation-in-flight oznacza, że trwa walidacja pliku, która nie zakończyła się w limicie czasu przyznanym przez oczekujące żądanie: należy wkrótce zapytać ponownie i niczego nie wysyłać, ponieważ potrzebny stan jest już w drodze, a druga walidacja tylko dodałaby pracy. Traktowanie obu jako jednego warunku prowadzi klienta do wysłania walidacji w sytuacji, w której jest to niewłaściwy ruch. Oba pasma znaczą dla klienta co innego: kod 1xxx wskazuje stan przestrzeni roboczej, na który użytkownik może zareagować — zwalidować plik, wygenerować lockfile — natomiast kod standardowy, taki jak invalid-params, wskazuje błędnie sformułowane żądanie, które poprawia klient, a nie użytkownik. Wartość release, która jest obecna, ale błędna — bezwzględna lub wskazująca poza katalog główny przestrzeni roboczej — należy do drugiego pasma: to nie przestrzeń robocza jest w stanie wymagającym naprawy przez użytkownika, lecz żądanie. Pominięcie release nie należy do żadnego pasma, ponieważ w ogóle nie jest błędem; wybiera węższą z dwóch odpowiedzi opisanych w sekcji Walidacja na żywo.

Błąd może zawierać obiekt data, a każdy klucz w nim wskazuje jedną rzecz i tylko tę rzecz. file to dokument źródłowy, którego dotyczy błąd — walidowany dokument, encja Release, której wczytanie się nie powiodło, dokument przestrzeni roboczej deklarujący nazwę, której nic nie rozwiązało, lub dokument, na który wskazuje odmowa zgłoszona podczas renderowania — i to w nim towarzyszące line i column lokalizują pozycję. Te dwa są same w sobie opcjonalne: błąd dotyczący całego dokumentu zawiera tylko file. lockfile to plik lockfile. release to encja Release, której dotyczy błąd, zapisana tak, jak wskazało ją żądanie, aby klient mógł złożyć aggrega pull --release <release> bez wyodrębniania jej z komunikatu. unreachable informuje, że z rejestrem wskazanym w odrzuconym żądaniu nie udało się połączyć: zawiera go odrzucone odświeżenie indeksu wskazujące jeden rejestr, odczytany z samego błędu, a rejestr, który odpowiedział, pozostawia go nieobecnym. Każdy klucz jest opcjonalny i obecny tylko wtedy, gdy demon ma daną wartość; żaden nie zastępuje innego, więc to, na co wskazuje klucz, nigdy nie zależy od kodu obok niego.

code i shortCode w data wskazują warunek zgłaszany przez odmowę w każdej odmowie zgłaszającej zarejestrowany warunek, niezależnie od jej kodu liczbowego: kod opisowy, według którego rozgałęzia się program, i krótki kod, który przytacza człowiek — te same dwa identyfikatory, pod tymi samymi nazwami, które zawiera wpis diagnostyczny dla tego samego warunku, wymienione w tabeli wszystkich warunków. Należy rozgałęziać według code. Kod liczbowy wskazuje stan żądania i pozostaje taki sam dla wielu warunków — kompilacja odrzucona, bo dowiązanie katalogu prowadzi na zewnątrz, i kompilacja odrzucona, bo nazwa nie rozwiązuje się do niczego, mają obie kod 1004 — a komunikat to proza, która może zostać przeredagowana, więc żadne z nich nie odróżnia jednego warunku od drugiego. Invalid-params jest jednym z takich wspólnych kodów: otrzymuje go także żądanie wskazujące przestrzeń roboczą, której plik konfiguracyjny prowadzi poza nią, a wtedy read-leads-out-of-workspace informuje, że winny jest układ przestrzeni roboczej, który naprawia człowiek, a nie żądanie. Odmowa niezgłaszająca zarejestrowanego warunku nie zawiera żadnego z tych kluczy, a oba występują razem albo wcale. Komunikat odmowy wskazującej warunek zaczyna się od jego krótkiego kodu, E0321: …, jeden raz, i w tej postaci czytelnik spotyka go w każdej takiej odmowie; odmowa, której komunikat już zaczyna się od nagłówka w nawiasach zawierającego kod — jednowierszowy raport o dokumencie katalogu odrzuconym przy wczytywaniu — nie otrzymuje go ponownie.

Opis przebiegu kaskady encji Release w przestrzeni roboczej jest przekazywany w odpowiedzi aggrega/activeRelease, w jej polu trace, a nie w błędzie: przestrzeń robocza niewskazująca żadnej encji Release to zwykły stan, a nie nieudane żądanie. Jest to proza diagnostyczna przeznaczona do czytania przez człowieka, a nie struktura do parsowania. Należy wyświetlać ją bez zmian — zapisać do logu lub w panelu, który użytkownik może otworzyć — i nie dopasowywać do niej wzorców, nie wyodrębniać z niej wartości ani nie rozgałęziać według używanych w niej etykiet: jej sformułowania, układ i etykiety podążają za samą kaskadą i zmieniają się za każdym razem, gdy zmienia się kaskada. Klient przekazujący tekst dalej działa nadal po takiej zmianie; klient, który nauczył się jego kształtu, przestaje działać.

Zobacz także

  • ../schema/other/serve-wire.md — kształty komunikatów wymienianych w tym protokole, wygenerowane z opublikowanego schematu: obiekt parametrów każdej metody, każdy wynik i ładunek każdego powiadomienia, pole po polu.
  • ./aggrega-build.md — polecenie build, którego potok kompilatora, bramki i rozwiązywanie zależności uruchamia również aggrega/build, dzięki czemu oba interfejsy zapisują jedno drzewo wyjściowe, a nie dwa.
  • ./aggrega-version.md — polecenie version, którego rozszerzenie edytora używa do sprawdzania zgodności z demonem.
  • ./aggrega-pull.md — plik blokady, który odczytuje mechanizm wykrywania rozbieżności demona.
  • ./aggrega-lint.md — konwencje publikowania, które demon zgłasza na żądanie, a po włączeniu serve.lint_on_validate także przy każdej walidacji.

Składnia

aggrega serve [flags]

Opis

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.

Flagi

FlagaDomyślnieOpis
--build-on-inspectfalseUruchamia etap renderowania artefaktów podczas inspekcji grafu IR, dzięki czemu ostrzeżenia, które aggrega build zgłasza podczas renderowania, pojawiają się również jako problemy w edytorze. Nie dodaje żadnego z testów, na których build się zatrzymuje. Nic nie jest zapisywane na dysku: żadne wyrenderowane artefakty, żaden katalog wyjściowy, żaden plik blokady. Domyślnie wyłączone, zgodnie z aggrega inspect, które również nie zgłasza takich ostrzeżeń. Gdy ustawione, nadpisuje klucz konfiguracji serve.build_on_inspect.