aggrega serve
aggrega serve ejecuta Aggrega como un daemon compiler-as-service de larga duración para la integración con IDE. Habla JSON-RPC 2.0 sobre stdin/stdout y mantiene el estado del catalog-resolver, la parse-cache y los diagnósticos entre solicitudes, de modo que las operaciones del editor obtienen respuesta en menos de un segundo en lugar de pagar el coste completo de carga del catálogo en cada pulsación de tecla.
El daemon normalmente lo inicia como subproceso una extensión del editor, no se ejecuta a mano. Una extensión de VS Code es el cliente de referencia; otros editores pueden integrarse hablando el mismo protocolo.
El protocolo
El protocolo de transmisión es JSON-RPC 2.0 con framing Content-Length, bajo el espacio de nombres de métodos aggrega/. Intencionadamente no es el Language Server Protocol — Aggrega tiene operaciones de dominio (una consulta al grafo IR, una señal de invalidación de caché) para las que LSP no tiene equivalente. Una extensión del editor traduce entre las solicitudes LSP del editor y estos métodos aggrega/*; los valores de posición, rango y ubicación con forma de LSP se reutilizan donde encajan.
Dos métodos conservan sus nombres $/ estándar del protocolo en lugar de renombrarse dentro del espacio de nombres aggrega/, porque ambos son cuestiones de transporte que no tienen ningún significado propio de Aggrega y un cliente que ya habla el protocolo los gestiona sin añadir nada: $/cancelRequest, que detiene una solicitud cuya respuesta el cliente ya no quiere, y $/progress, que es como el daemon informa de una operación larga mientras se ejecuta. Ambos se describen más abajo.
🔴 Cada solicitud de abajo lleva workspaceRoot, la ruta absoluta del espacio de trabajo sobre el que actúa, y esto no se repite en cada método. Tres no la llevan, porque su objeto no es un espacio de trabajo: aggrega/initialize, aggrega/getSchema y aggrega/scaffoldEntity — salvo que aggrega/scaffoldEntity sí nombra uno cuando escribe o lista un ejemplo ejecutable. Consulta Cada solicitud nombra el espacio de trabajo al que se refiere para saber qué obtiene una solicitud que no nombra ninguno, y Declarar el espacio de trabajo para el que quieres recibir diagnósticos para saber adónde van los diagnósticos enviados.
Las formas campo por campo se publican como un esquema, y la referencia de formas de transmisión es donde leerlas. Esa página indica el objeto de parámetros de cada método, cada resultado y cada carga útil de notificación — cada campo con su tipo, si es obligatorio y qué lleva — junto con tres propiedades que se cumplen en toda la superficie en lugar de por método: los dos campos que toda solicitud admite además de los que declara su propio método, que son workspaceRoot arriba y el workDoneToken de Observar una operación larga; que un objeto params que lleva una clave que su método no acepta se rechaza, nombrando en el rechazo el conjunto aceptado; y dónde una colección ausente llega al cable como null en lugar de como una colección vacía. Se genera a partir de ese esquema, así que cambia cuando cambia el contrato.
Esta página lleva el protocolo, aquella lleva las formas, y están pensadas para leerse juntas. Aquí: el framing, para qué sirve cada método, hasta dónde llega, qué escribe, qué rechazos produce y por qué, los códigos de error y qué hacer con cada uno. Allí: qué poner en el cable, clave por clave. Así, la lista de abajo nombra cada método y dice qué significa preguntarle, y la lista de campos de la solicitud que estás componiendo está en la referencia de al lado.
Solicitudes:
aggrega/initialize— handshake. Negocia la codificación de posiciones (el servidor prefiere UTF-8, luego UTF-16, luego UTF-32, y usa UTF-16 de forma predeterminada), recibe el espacio de trabajo que declaras para los diagnósticos enviados e informa de la raíz de ese espacio de trabajo, la capa de configuración de la que se resolvieron sus ajustes y el marcador que la resolvió. La respuesta lleva tambiénversion, la versión del binario que responde: el mismo valor queaggrega versioninforma para ese binario. Describe el proceso que se está ejecutando, así que, una vez reemplazado el archivo desde el que se inició el daemon — por una recompilación en la misma ruta, por ejemplo —,versionsigue nombrando el daemon en ejecución mientras que preguntar al archivo nombra a su sustituto; léelo aquí cuando la pregunta sea con qué versión estás hablando.workspaceRootes opcional y declara un espacio de trabajo en lugar de actuar sobre él — consulta Declarar el espacio de trabajo para el que quieres recibir diagnósticos. Envíacapabilities.window.workDoneProgress: truepara indicar que tu cliente puede gestionar notificaciones de progreso;capabilities.workDoneProgressen la respuesta lo repite, y el campo está ausente para un cliente que no declaró nada. Consulta Observar una operación larga.aggrega/validate— valida el contenido de un archivo; devuelve diagnósticos.releasees una ruta relativa a la raíz del espacio de trabajo que nombra la Release contra la que validar — el mismo valor que tomaaggrega/irGraph, y el mismo valor que tomaaggrega build --releasecuando se ejecuta desde la raíz. Es opcional y determina hasta dónde llega la respuesta: si nombras una Release, las comprobaciones que necesitan una se ejecutan contra ella — una entidad de catálogo se comprueba como entidad individual en los términos de esa Release, y cualquier otro documento contra el cierre de dependencias de esa Release; si lo omites, la respuesta cubre lo que se le puede exigir al documento por sí solo, y llevacheckedpara indicarlo. Un valor presente pero mal formado se rechaza en cualquier caso — una ruta absoluta, o una que se resuelve fuera de la raíz del espacio de trabajo, se rechaza en lugar de resolverse. Consulta Validación en vivo.aggrega/diagnostics— devuelve los hallazgos conservados para un archivo. Si cuando llega la solicitud se está ejecutando una validación de ese mismo archivo, la respuesta la espera e informa de lo que encontró, de modo que la respuesta nunca es un certificado de buena salud para un archivo en el que el daemon está a mitad de encontrar problemas. Consulta Pedir diagnósticos mientras se ejecuta una validación.aggrega/hover— contenido hover para la entidad en una posición.releasees opcional y responde en los términos de esa Release — consulta Responder en los términos de una Release.aggrega/completion— candidatos de completado en una posición. Donde el cursor nombra una entidad por tipo — eltypede un componente, eltypede un acoplamiento de Feature, un valorextends:, elimplements:de una Recipe o de una FeatureRecipe —, los candidatos son los nombres de ese tipo que declaran los propios documentos de tu espacio de trabajo y, para un Component o una Feature, también los nombres que declaran tuscatalog_dirsconfigurados, cada uno ofrecido una vez y por orden de nombre. Por lo tanto, a un espacio de trabajo que toma sus Components y Features de un catálogo se le ofrecen estos, no solo lo que él mismo escribió. Las Recipes y FeatureRecipes, ofrecidas en el valor de una asignación del Manifest, proceden de los propios documentos del espacio de trabajo. No se ofrece una entidad que solo tenga la caché de artefactos o un registro: responder a un completado nunca descarga nada.releasees opcional y responde en los términos de esa Release — consulta Responder en los términos de una Release.aggrega/resolve— resuelve la entidad referenciada en una posición (ir a la definición).releasees opcional y responde en los términos de esa Release — consulta Responder en los términos de una Release.aggrega/findReferences/aggrega/findImplementations. Cada uno toma unreleaseopcional y responde en los términos de esa Release — consulta Responder en los términos de una Release.aggrega/irGraph— el grafo IR compilado de una Release, para la introspección en el editor.releasees una ruta relativa a la raíz del espacio de trabajo que nombra una Release dentro de él — el mismo valor que tomaaggrega build --releasecuando se ejecuta desde la raíz. Cualquier otra forma se rechaza con el error estándar invalid-params que nombra qué enviar en su lugar: una ruta absoluta, una ruta que se resuelve fuera de la raíz del espacio de trabajo — tanto si sale tal como está escrita como si sale a través de un enlace, al archivo o a un directorio del camino — y un valor vacío se rechazan todos en lugar de resolverse, de modo que una solicitud nunca informa sobre un archivo que el espacio de trabajo no contiene. Una Release que nombra la configuración de tu espacio de trabajo, comobuild.authoring_releaseo como clave deworkspace.releases, pertenece al espacio de trabajo dondequiera que esté su archivo, así que se acepta un enlace dentro del espacio de trabajo que lleve a ella, tal como la listaaggrega/releaseCandidates. Un directorio de catálogo que lee la Release y que no se puede recorrer — uno que existe y no se puede leer, por ejemplo — se rechaza como lo rechazaaggrega inspect, antes de leer nada más: el error es1004entity-not-resolvable, su mensaje es el informe que imprime la línea de comandos para ese directorio, en una línea ([CATALOG_ERROR] <directory>: catalog load: …), y no se traza ningún grafo sobre los directorios restantes. Un directorio que lista la configuración del espacio de trabajo y que no es un directorio — no existe nada allí, por ejemplo — se rechaza de la misma manera y en el mismo momento,1004entity-not-resolvable, con el mensaje del rechazo que le da cualquier comando, que nombra la entrada, el archivo y la línea de configuración que la listan y el ajuste (Desde dónde se leen las entidades locales). Un directorio de catálogo que contiene un enlace que sale del directorio dentro del cual deben quedarse sus lecturas — un documento o un directorio enlazado desde otro lugar, bajo un directorio de catálogo dentro del espacio de trabajo o bajo uno que la configuración nombra fuera de él — se rechaza de la misma manera y en el mismo momento, con1004y la frase propia de la condición que nombra el enlace y adónde lleva: no se lee nada a través de un enlace así, y un grafo trazado sin él podría resolver en su lugar otra entidad con el mismo nombre. Lo mismo ocurre con un enlace que sale de los documentos que están junto a la Release, donde la Release nombra su Aggregate o su Manifest por identidad. Un archivo que la Release, su Manifest o una Release que esta extiende nombra mediante una ruta —aggregate:,manifest:,extends:o un$import:de parameters — y que sale del espacio de trabajo, tal como está escrito o a través de un enlace, se rechaza con la frase propia de la condición (fatal-halts.md §«A reference to another file leads out of the directory it must stay inside (Una referencia a otro archivo sale del directorio dentro del cual debe permanecer)»), con los datos del error situándolo en la clave de la Release que llevó al archivo, y no se lee nada de ese archivo; una Release que la configuración nombra fuera del espacio de trabajo se ciñe de la misma manera al directorio que la contiene, así que también se rechaza una ruta que escriba ella, o una Release a la que lleve su cadena, y que salga de ese directorio. Ten en cuenta queaggrega/releaseCandidatesresponde con rutas absolutas, así que un cliente que alimenta una superficie con la otra convierte entre ambas. Que este parámetro rechace una grafía que los parámetros por documentofileyuriaceptan es deliberado, y Qué grafías acepta un parámetro que envías explica qué lo decide. El grafo oculta cada valor que un autor declaró sensible, exactamente como lo oculta--ir-graphen la línea de comandos: cada uno se sustituye por el marcador que describeaggrega-inspecten «Salida legible por máquina», y todo lo demás se lleva tal como lo registró el compilador.unredacted: truepide esos valores en claro — la grafía del protocolo para el--unredactedde la línea de comandos, y la única forma de pedirlos; si está ausente o esfalse, la respuesta los oculta. Todo lo que alcanza la respuesta lleva entonces los valores en claro, así que un cliente solo los pide donde lo ha hecho la persona que lo usa.aggrega/build— compila una Release y escribe sus artefactos en el directorio de salida del espacio de trabajo, el mismo directorio en el que escribeaggrega buildcuando se ejecuta desde la raíz del espacio de trabajo.releaselleva el mismo contrato que arriba. Renderiza con todos los controles activos, así que una divergencia en la que se detendría una compilación desde la línea de comandos también se detiene aquí. Un directorio de catálogo que lee la Release y que no se puede recorrer — uno que existe y no se puede leer, por ejemplo — se rechaza como lo rechazaaggrega build, antes de escribir nada: ningún artefacto, y ningún lockfile cuandoautoPullestá activado. Lo mismo ocurre con un directorio que lista la configuración del espacio de trabajo y que no es un directorio, en los términos en que lo rechazaaggrega build(De dónde se leen las entidades locales). El rechazo es el que daaggrega/irGraphpara el mismo directorio,1004entity-not-resolvable con el informe de la línea de comandos en una sola línea, y un enlace que sale de las lecturas de un directorio de catálogo, o de los documentos junto a la Release, se rechaza como lo rechazaaggrega/irGraph, sin escribir nada. La respuesta nombra eloutputDirectoryen el que escribió y losfilesque escribió, cada uno relativo a ese directorio y ordenados, junto con lasnoticesque haya generado la ejecución; los hallazgos que llevan una posición en el documento viajan en cambio poraggrega/publishDiagnostics. A una Release que se rechaza mientras se renderiza se le responde con ese rechazo en las palabras del compilador, con todas sus causas, y el rechazo se publica donde apunta — consulta Un rechazo generado durante el renderizado. CuandoautoPullestaba activado, la respuesta lleva tambiéndependencyResolution, el mismo informe con el que respondeaggrega/resolveDependencies, de modo que un cliente que rellenó las dependencias como parte de la compilación lee lo que se fijó sin volver a preguntar — y de dónde tomó la resolución de esta compilación cada referencia, un dato sobre esa ejecución que el lockfile no registra. Cada aviso lleva laclassde la superficie que lo generó —deprecation,catalog,catalog-lint,extends,release-composition, odependency-resolutionpara una línea generada por la resolución de dependencias descrita más abajo — y unaclassvacía cuando el daemon no tiene nombre para esa superficie, que un cliente muestra como eltextsin más en lugar de adivinar la coincidencia más cercana. Los archivos que la escritura encuentra en el directorio de salida, o en un directorio por debajo de él en el que escribió un archivo o por el que pasó, y que esta compilación no escribió se dejan donde están y se nombran en un único aviso después de los de la propia ejecución, bajo unaclassvacía, en la frase con la queaggrega buildimprime su advertencia — consulta Archivos que la compilación no escribió;filesnunca los nombra.outputParentdice dónde van los artefactos dentro del espacio de trabajo, y su nombre es todo lo que significa: es el directorio dentro del cual se crea el directorio de salida, así que enviardocsescribe los artefactos endocs/disty no endocsmismo — exactamente lo que produce una compilación ejecutada endocsdesde una terminal. Si lo omites, la compilación escribe donde escribe una ejecutada en la raíz del espacio de trabajo. Se lee de forma distinta deloutputDirque aceptan las demás solicitudes de escritura de aquí, y a propósito: esas nombran el directorio en el que se escribe, este nombra el directorio padre de ese, y los dos llevan nombres distintos porque son cosas distintas. Sigue siendo un destino dentro del espacio de trabajo, así que un valor absoluto, uno que sube fuera de la raíz y uno que sale de ella a través de un enlace — un directorio enlazado fuera de la raíz, o un directorio aún no creado por debajo de uno así — se rechazan en lugar de resolverse. El directorio de salida creado dentro de él, y cada archivo que la compilación escribe allí, quedan sujetos también al espacio de trabajo: cuando uno de ellos sale del espacio de trabajo a través de un enlace, la compilación se rechaza con1004y la frase propia de la condición, que nombra el enlace y adónde lleva, y no se vacía ni se escribe nada.autoPullresuelve las dependencias de la Release antes de renderizar, la misma resolución que realizaaggrega/resolveDependencies, y está desactivado a menos que una solicitud lo pida, en línea con el valor predeterminado de la propia línea de comandos; sin él, una Release que no tiene lockfile se rechaza con el error lockfile-absent, que nombra qué ejecutar. ConautoPullactivado, esta solicitud llega a los registros y escribe el lockfile — consulta Llegar a un registro, y escribir. Una solicitud que resuelve primero sigue renderizando la Release una sola vez: averiguar qué referencias remotas consume una Release es en sí un renderizado, así que la resolución ya ha renderizado aquello de lo que trata la compilación, y la compilación se responde a partir de ese renderizado en lugar de repetirlo.policyInputnombra un directorio dentro del espacio de trabajo, relativo a su raíz, en el que la compilación escribe también la carga útil que cada rol de gobernanza entrega a un plugin adjunto allí — los archivos que escribeaggrega build --policy-input, con los mismos nombres —, tanto si la compilación termina como si se detiene; lasnoticesde la respuesta dicen entonces cuántos se escribieron y nombran cada rol para el que no se escribió ningún archivo, bajo unaclassvacía. En una solicitud que falla, los archivos escritos están en disco y ese recuento no está en la respuesta: el sobre de error lleva solo el rechazo. Es un destino, así que un valor absoluto o uno que sube fuera del espacio de trabajo se rechaza antes de que se ejecute nada.aggrega/buildPreview— informa de lo que escribiría una compilación de la Release, sin escribir nada de ello.releaselleva el mismo contrato que arriba. Ejecuta el mismo cálculo queaggrega/build, con los mismos controles, así que una Release o se rechazaría en ambas o se informa en ambas — y eso es lo que hace que elegir entre ellas sea una elección sobre la salida y no sobre el rigor. Un directorio de catálogo que lee la Release y que no se puede recorrer, o que contiene un enlace que sale del directorio dentro del cual deben quedarse sus lecturas, se rechaza de la misma manera, antes de renderizar nada, y lo mismo ocurre con un directorio que lista la configuración del espacio de trabajo y que no es un directorio, como enaggrega/build. La respuesta llevafiles, los nombres relativos a la salida que emitiría una compilación, ordenados, junto con lasnoticesque haya; no hayoutputDirectory, porque no se escribió nada en ningún sitio que nombrar. A una Release que se rechaza mientras se renderiza se le responde, y se publica, exactamente comoaggrega/buildle responde y la publica. RechazaautoPullcon un error invalid-params que nombra qué enviar en su lugar: rellenar las dependencias escribe el lockfile, y esta solicitud no escribe ningún lockfile. No llega a ningún registro.policyInputes la única escritura que hace, y solo cuando se envía: escribe las cargas útiles de gobernanza en ese directorio exactamente como lo haceaggrega/build— los archivos que escribeaggrega build --dry-run --policy-input—, sin tocar el directorio de salida ni el lockfile, con el mismo recuento en lasnoticesy el mismo límite: en una solicitud que falla, los archivos escritos están en disco y el recuento no está en la respuesta.aggrega/resolveDependencies— resuelve las dependencias de catálogo y de origen de la Release en la caché, fija en el almacén direccionado por contenido las entradas externas que consume su renderizado y escribe su lockfile.releasees una ruta relativa a la raíz del espacio de trabajo, el mismo valor que tomaaggrega/irGraph, y se rechaza en las mismas formas.upgradedescarta las fijaciones registradas y vuelve a resolver, llevando cada dependencia a la versión disponible más alta;targetslimita esto a las referencias de entidad que nombra, manteniendo todas las demás fijaciones.verifycomprueba la resolución registrada contra la que esta solicitud realizaría sin él, respetando de la misma manera las fijaciones registradas, y no escribe ningún lockfile, registro de confianza de plugins nientity.lock— la caché se lee y se rellena como se haría sin él — y respondeverified: truey eltoolchainque registra el lockfile.verifyse rechaza como parámetros no válidos junto aupgrade, junto atargetsy junto apinSources, sea cual sea su valor, antes de resolver nada o de informar de ningún progreso: un upgrade descarta las fijaciones que un verify existe para respetar, los destinos nombrados solo se vuelven a resolver mediante un upgrade, ypinSourcesdecide si una resolución registra las fijaciones que le faltan a unentity.locko se rechaza por ellas, y ninguna de las dos cosas la hace una comparación que no escribe ningúnentity.lock. La línea de comandos y la herramienta del asistente rechazan los mismos pares. La respuesta nombra ellockfileque escribió o con el que comparó y cada referencia que fijó, enentities,librariesyplugins, cada entrada con laversiona la que se resolvió y susource— de dónde tomó la referencia esta ejecución, con la palabra que imprimeaggrega pull --detailpara la misma resolución:fetched-fresh,cache-reuse,local,in-binaryoexternal— junto consourceArtifacts,trustedPlugins,externalInputs— cuántas entradas externas fija el lockfile una vez terminada la ejecución, contando tanto las que se arrastraron como las que descubrió esta ejecución — y lasnoticesque haya producido la resolución. 🔴 Una respuesta correcta no significa por sí sola que la fijación de entradas externas esté completa. Donde la ejecución fijó todas las dependencias pero no pudo terminar de averiguar qué entradas externas consume la Release, responde conincompleteExternalInputsindicando qué detuvo el descubrimiento, y aun así responde como un éxito — las fijaciones de dependencias están completas y en disco, así que informar de toda la solicitud como fallida te diría que rehicieras un trabajo que ya es correcto. Lee ese campo antes de tratar un lockfile como totalmente fijado: está ausente cuando no quedó nada sin descubrir, así que su presencia es la señal. No hay ningún parámetro de directorio de catálogo: la pila de búsqueda es la que configura el espacio de trabajo. Esta es la única solicitud de fijación de la sesión para una Release, y es donde también se fijan las entradas externas — qué URL consume un renderizado se deriva de lo que renderiza, así que esta solicitud renderiza la Release para averiguarlo, y después una solicitud de compilación se sirve a partir de lo que registró. Una Recipe o FeatureRecipe que compila la Release cuyoentity.lockno registra ninguna fijación para una entrada que lee la entidad hace que se rechace la solicitud, nombrandoaggrega piny cada entrada sin registrar;pinSources: trueejecuta en cambio ese paso de fijación sobre esas entidades, escribiendo elentity.lockjunto a cada una — el mismo paso que ejecutaaggrega/pin, que escribe los mismos bytes. Si está ausente,pinSourcessigue elpin_sources_at_pulldel espacio de trabajo; si se envía, anula ese ajuste en ambos sentidos, así quefalserechaza incluso en un espacio de trabajo configurado para fijar. Esta solicitud llega a registros y escribe — consulta Llegar a un registro, y escribir.aggrega/pin— registra, en elentity.lockque está junto a una Recipe o FeatureRecipe, la fijación de contenido de cada entrada que la entidad lee fuera de su propio documento: un origen remoto cuyas coordenadas están escritas por completo, un archivo que importa una entrada artifacts y cada archivo que un origen local aporta a lo que contiene una publicación de la entidad. Es el mismo paso que ejecutaaggrega pinen un terminal, y escribe los mismos bytes.entityes obligatorio y es una ruta relativa a la raíz del espacio de trabajo que nombra el documento de la entidad, y se rechaza en las mismas tres formas querelease. No se nombra ninguna Release: un origen remoto cuyas coordenadas no llevan plantilla nombra un único artefacto para cada Release que usa la entidad, así que no se necesita nada de lo que aporta una Release para fijarlo, mientras que un origen remoto cuyas coordenadas proceden de una plantilla lo fija por Releaseaggrega/resolveDependencies; un origen local escrito como plantilla aporta cada archivo del directorio de la entidad, y cada uno de ellos se fija aquí.dryRunresuelve las entradas y responde con el lock que escribiría el paso comocontent, sin escribir nada junto a la entidad; la caché de contenido se rellena igualmente. La respuesta llevaentity,kind,nameypinnable— false para un tipo que no lee nada que registre un lock, en cuyo caso no se tocó nada junto a la entidad y todos los demás campos están ausentes — y, en otro caso, ellockque escribió,changed(false cuando el lock ya registraba todas las fijaciones y se dejó idéntico byte a byte),removeddonde la entidad ya no lee nada que registre un lock y su lock se eliminó, ypins, una entrada por clase de fijación con el número que contiene el lock. El archivo de la entidad en sí nunca se escribe. Esto escribe junto a la entidad, dentro del espacio de trabajo, y llega a los hosts que nombran los orígenes de la entidad — consulta Llegar a un registro, y escribir.aggrega/cacheStatus— lo que contienen las cachés en disco: una entrada por elemento en caché con su tamaño y, donde lo tiene, su digest de contenido, agrupadas por clase. Toma el espacio de trabajo y nada más. Cada clase lleva unreach—workspacepara la caché de artefactos bajo el propio directorio de caché de este espacio de trabajo,machinepara los almacenes de módulos compilados, de descripciones de plugins y de paquetes de documentación que comparten todos los proyectos de la máquina — yscopenombra directamente las clases de toda la máquina. No escribe nada. Consulta Llegar a un registro, y escribir para saber por qué el alcance figura en una respuesta que no cambia nada.aggrega/cachePrune,aggrega/cacheEvict,aggrega/cacheClear— recuperan espacio del contenido en caché. Un prune elimina lo que no referencia ningún lockfile del espacio de trabajo; una evicción recorta el almacén de módulos compilados amaxSize, una cantidad de bytes escrita como la escribe la línea de comandos (5GiB,512MiBo un número de bytes); un clear vacía todas las cachés a las que se dirige esta sesión. Cada respuesta nombra lo que eliminó, con cada eliminación llevando elreachde la clase de la que procede, y cada una llevascope. Cada respuesta nombra también lo que dejó en su sitio porque otro proceso lo tenía abierto — Windows se niega a eliminar un archivo abierto, y la operación continúa con el resto en lugar de fallar: un prune o una evicción lista esas entradas enheldOpen, y un clear cuenta, para cada caché que vació, los archivos que dejó enheldOpenFilesy su tamaño enheldOpenBytes. En otros sistemas la lista está vacía y los recuentos son cero, y una ejecución posterior puede recuperar lo que quedó. Estas llegan más allá del espacio de trabajo — consulta Llegar a un registro, y escribir.aggrega/registryList— los registros a los que este espacio de trabajo está configurado para llegar: para cada entrada, el host, el alias opcional, si es el predeterminado, su postura de confianza como campos separados y si hay una credencial para ese host. Toma el espacio de trabajo y nada más. No contacta con ningún registro. El estado de la credencial informa solo de su presencia — nunca de la credencial, nunca de su forma, y nunca de si el registro la aceptaría, lo que requeriría un viaje de ida y vuelta por la red que un listado no realiza — y se lee del almacén de credenciales de toda la máquina, algo quecredentialStateIsMachineWidedice explícitamente.aggrega/search— busca en el índice local de los registros configurados. Cada campo acota la búsqueda y todos son opcionales, así que un objeto params vacío pide todo lo que contiene el índice. No contacta con ninguna red: el índice es la instantánea sin conexión escrita bajo el propio directorio de caché de este espacio de trabajo. La versión informada es la que tomaría una resolución — una versión cuya retirada lleva una firma en la que confía este espacio de trabajo se excluye y se nombra enretracted— y la respuesta lleva su propia procedencia:indexesda la antigüedad de la instantánea de cada registro buscado,stalemarca la que conviene actualizar ymissingIndexHostsnombra los registros configurados sin índice local, cuyo contenido está por tanto ausente de la respuesta.aggrega/registryAdd— da de alta un registro y su política de confianza de firmas.hostes obligatorio; todo lo demás da forma a la política o al destino de escritura.keyPathytrustedRootnombran archivos: un valor absoluto — un archivo elegido en un cuadro de diálogo, por ejemplo — se lee donde indica; uno relativo nombra un archivo dentro del espacio de trabajo, resuelto respecto a la raíz del espacio de trabajo en lugar de respecto al directorio en el que se ejecuta el daemon, y uno que sube fuera de la raíz o sale de ella a través de un enlace se rechaza con el error invalid-params antes de leer o escribir nada. UntrustedRootrelativo se registra como el archivo que nombra en el espacio de trabajo, de modo que la entrada nombra ese archivo sea cual sea el directorio en el que se ejecute una verificación posterior.fetchTrustvale true de forma predeterminada cuando la clave está ausente, igual que en la línea de comandos, y adopta en el primer contacto la política anunciada por el propio registro;trusten la respuesta dice qué ocurrió — se fijó la política, el registro no anunciaba ninguna (y, conunreachableal lado, no se pudo llegar a él en absoluto), se fijó en su lugar la línea base integrada del hub oficial, o no se intentó ninguna obtención. El alta es la que realizaaggrega registry add: la misma obtención con la misma postura de red, que escribe la misma entrada byte a byte. En un espacio de trabajo sin conexión, la obtención se rechaza antes de marcar nada, así que nunca se pregunta al registro, y se rechaza un registro distinto del hub oficial salvo que la solicitud aporteidentitiesokeyPath, que dan de alta exactamente lo que se envió y no realizan ninguna obtención: el mensaje del error es la frase que imprime la línea de comandos, precedida del código corto de la condiciónE0310— igual que el mensaje de cada rechazo de esta solicitud que nombra una condición empieza por su código corto — y no se escribe nada. El hub oficial se sigue escribiendo con su línea base integrada, con una respuesta que llevatrust.baselinea true ytrust.reasondiciendo que no se pidió al hub su política de confianza porque el espacio de trabajo está sin conexión — el motivo con el que empieza el aviso de la línea de comandos — y sinnotAdvertised, porque nunca se preguntó al hub. Esto escribe la configuración global de forma predeterminada — consulta Llegar a un registro, y escribir.aggrega/registryRemove— elimina la entrada de un registro, indicado por host o alias descriptivo. Un token que no coincide con nada se rechaza en lugar de responderse como un éxito sobre una configuración sin cambios. Esto escribe la configuración global de forma predeterminada — consulta Llegar a un registro, y escribir.aggrega/logout— elimina la credencial almacenada para un registro, la misma eliminación que realizaaggrega logouten un terminal.registryes obligatorio y nombra el host del registro tal como te autenticaste en él; aquí no hay ningún alias descriptivo que resolver, porque el almacén de credenciales se indexa por la dirección en la que se autentica un cliente y no por algo que nombre una configuración, así que un host que ningún espacio de trabajo configura puede seguir teniendo una credencial que puedes eliminar. Un host para el que el almacén no tiene ninguna credencial se elimina correctamente y no se reescribe nada — quien pidió que un host no tuviera credencial ha obtenido lo que pedía, así que es una respuesta y no un error, y es también lo que hace el comando del terminal. La respuesta llevaregistryyscope. No lleva ninguna parte de la credencial en ninguna forma, y no informa de nada sobre si había una: averiguarlo requeriría una segunda lectura del almacén que nadie ha pedido, así que pregunta aaggrega/registryListcuando la cuestión sea la presencia. No contacta con ningún registro — eliminar una credencial almacenada es un acto local, y no se pregunta si ese registro habría aceptado la credencial. Esto cambia el almacén de credenciales que comparten todos los proyectos de la máquina — consulta Llegar a un registro, y escribir.aggrega/registryUpdate— actualiza el índice local consultable que leeaggrega/search. Unregistryausente actualiza todos los configurados; nombrar uno actualiza solo ese registro.upgradevuelve a leer por completo cada repositorio, sin comparar nada con el índice ya escrito; una actualización sin él ya vuelve a leer todo lo que cambió. La respuesta lleva el número de registros de cada host, los repositorios que no pudo leer — cada uno con unreasonque empieza por el tipo del último fallo de la lectura, donde lo hay —,readsRetried, cuántas de sus lecturas el registro rechazó o interrumpió por el camino y se volvieron a pedir, cada una contada una vez y cero incluido, los marcadores de obsolescencia que encontró, elerrorde un host que falló — conunreachableal lado donde no se pudo llegar a ese registro — eindexRoot, el directorio bajo la propia caché de este espacio de trabajo en el que se escribieron los índices. Esto llega a cada registro que actualiza — consulta Llegar a un registro, y escribir.aggrega/publishEntity— empaqueta una entidad del catálogo y la publica en un registro.entityes una ruta relativa a la raíz del workspace que nombra el documento que se va a publicar, rechazada en las mismas tres formas querelease: ausente, absoluta o que se resuelve fuera de la raíz. Una entidad Plugin también necesitaplugin, el mismo tipo de ruta, que nombra el ejecutable publicado dentro del manifiesto propio de la entidad.registryes el destino y su valor predeterminado es el configurado en el workspace.dryRuncalcula el bundle y el digest en el que acabaría una publicación de este, y no contacta con ningún registro. Omitirsignsigue la política propia del registro de destino, que es lo que hace la línea de comandos cuando falta su flag, mientras que enviarlo es decisión de quien llama, y ninguna de las dos cosas relaja el rechazo, porque una política del registro o del workspace que exige una firma rechaza una publicación sin firmar diga lo que diga el campo.pinSources: trueejecuta el paso de pin del autor de la entidad sobre la entidad antes de empaquetarla, de modo que elentity.lockque el paso escribe junto a ella forma parte de lo que se publica: el mismo paso que ejecutaaggrega/pin. Se ejecuta antes de cualquier rechazo que juzgue el contenido de la entidad (una política de firma, la protección de inmutabilidad), de modo que una publicación rechazada en ese punto deja igualmente escrito el lock; un rechazo relativo a la propia solicitud, como un workspace sin conexión o la falta de destino, llega primero y no fija nada, y lo mismo ocurre con el rechazo de una entidad que comparte su directorio con otra entidad, en el que el paso no debe escribir un lock. Si está ausente, sigue el ajustepin_sources_at_pushdel workspace; si se envía, anula ese ajuste en ambos sentidos. CondryRun, el paso informa del lock que escribiría y no escribe nada. Una publicación que no ejecuta el paso rechaza una Recipe o una FeatureRecipe cuyoentity.lockno registra ningún pin para una entrada que lee, o uno con el que la entrada ya no coincide, antes de empaquetar nada (también condryRun), nombrandoaggrega pin,pinSourcesypin_sources_at_push; es el rechazo queaggrega/resolveDependenciesgenera sobre el mismo lock. La respuesta incluyereference,tag,kind,mediaType, el parsize, eldigestpublicado (condryRun, el digest en el que acabaría esa publicación, el que imprimeaggrega push --dry-run),signed,alreadyPublished,dryRunyreach;pin(la misma respuesta que daaggrega/pin) donde se ejecutó el paso; ywholeDirectorySourcedonde la fuente local de la entidad está escrita como plantilla, nombrando esa fuente tal como se escribió. Una fuente así elige su directorio solo cuando una Release rellena la plantilla, de modo que la publicación lleva cada archivo del directorio de la entidad en lugar de solo los archivos que la entidad nombra, y este campo es la forma en que quien llama se entera de que así ha sido, también en una ejecución de prueba. También incluyewindowsUnusableEntriesdonde el archivo comprimido que lleva la publicación contiene entradas que Windows no puede contener tal como están escritas (una ruta con una parte que lleva el nombre de un dispositivo, comoCON,AUXoNUL, en cualquier combinación de mayúsculas y minúsculas y con cualquier extensión que siga, o una parte que termina en un punto o un espacio), nombrando cada una: primero el nombre de archivo del propio documento de la entidad y luego los archivos que lleva; está ausente donde no hay ninguna, lo que incluye una entidad publicada solo como su documento.aggregaejecutándose en Windows se niega a desempaquetar una entrada así, de modo que un workspace de Windows no puede usar la versión. Son las entradas sobre las que advierteaggrega push, y una solicitud que pidió recibir informes lee las mismas líneas de advertencia entre el progreso de la publicación; ninguna de las dos cosas rechaza nada, de modo que la publicación sigue adelante o se rechaza exactamente como lo haría sin ellas, también condryRun. Esto escribe en un registro y llega más allá de esta máquina, y con el paso de pin también escribe junto a la entidad; consulta Acceder a un registro y escribir.aggrega/publishArtifact— publica un artefacto de datos independiente, como un bundle de documentación.filees una ruta relativa a la raíz del workspace, sujeta al mismo contrato, y sus bytes se publican literalmente: no se analiza ningún envoltorio de entidad ni se despacha según ningún kind.nameytagindican con qué nombre se publica, y ambos son obligatorios. El valor predeterminado demediaTypees el tipo de bundle de documentación. La respuesta incluyereference,tag,mediaType, el parsize, eldigestpublicado,alreadyPublished,dryRunyreach. No firma nada: un artefacto publicado se firma después por referencia conaggrega/signArtifacts, que solo necesita la referencia que informa esta respuesta. Esto escribe en un registro y llega más allá de esta máquina; consulta Acceder a un registro y escribir.aggrega/signArtifacts— firma artefactos ya publicados y adjunta cada firma.referencescontiene una o más direcciones de registro en lugar de rutas, de modo que no están sujetas a ningún contrato relativo al workspace; una lista vacía, o una entrada vacía en ella, se rechaza. Una única identidad sirve para todo el lote y se resuelve antes de firmar cualquier referencia, de modo que un lote sin ninguna credencial disponible se rechaza al principio en lugar de a mitad de camino. Lo mismo ocurre con un lote cuyas referencias necesitarían credenciales distintas: una solicitud no nombra ninguna clave, así que se trata de la configuración del workspace que nombra una clave disponible para el registro de una referencia y ninguna, u otra clave, para el de una segunda; no se firma nada, y el rechazo nombra los registros de cada lado, como describe References signed together need different signing credentials (Las referencias firmadas juntas necesitan credenciales de firma distintas). Firmar una referencia en la que no se publicó nada se rechaza en lugar de adjuntarse a nada, y una referencia que ya lleva una firma que verifica la política de confianza de su registro se deja como está y se cuenta como firmada, como describeaggrega sign.jobs, que es opcional, indica cuántas referencias se firman a la vez: si falta, se firman una tras otra, y un valor inferior a 1 se rechaza con el error invalid-params antes de leer ninguna referencia. Cada referencia se firma de todos modos exactamente como se firmaría sola, como describeaggrega sign, y tanto el progreso que informa la solicitud como la respuesta mantienen el orden en que se dieron las referencias. La respuesta incluyesigned, donde cada entrada nombra unareferencey eldigestpublicado con el que se compromete su firma, junto conreach; un lote en el que cualquier referencia falló recibe como respuesta un fallo que las nombra una a una en lugar de un resultado con una lista más corta. Esto escribe en un registro y llega más allá de esta máquina; consulta Acceder a un registro y escribir.aggrega/deprecateArtifact— adjunta un marcador de obsolescencia firmado a un artefacto ya publicado. Envía una únicareferencecon suseverityy sureason, o bienfrom, que nombra un archivo de lote relativo a la raíz del workspace; enviar ambos se rechaza. Los campos de contenido son obligatorios en lugar de solicitarse de forma interactiva: nadie está observando este flujo, de modo que una solicitud a la que le falta uno se rechaza indicando qué enviar. Pertenecen solo a lareferenceúnica: un archivo de lote lleva el contenido de cada marcador en sus propias entradas, de modo que unaseverity, unreason, unreplacemento unmessageenviados junto afromse rechazan como parámetro no válido, nombrando cada uno de los enviados, en lugar de ignorarse. Aquí se aplican las mismas entradas sin clave que aceptan las dos solicitudes de firma, porque el marcador se firma por su propio digest, y las entradas de un archivo de lote quedan sujetas a una única credencial exactamente como lo están las referencias de un lote de firma. La respuesta incluyemarked, donde cada entrada nombra lareferenceretirada, suseverity, la marca de tiempoissuedOny eldigestdel manifiesto propio del marcador (el marcador se adjunta como referrer sin etiqueta del artefacto que retira, así que nada más lo direcciona), junto conreach. Esto escribe en un registro y llega más allá de esta máquina; consulta Acceder a un registro y escribir.aggrega/catalogIndex— el índice de entidades: elkind, elname, laapiVersion, ladescription, laslabels, el archivo fuente y eloriginde cada entidad del workspace que nombró la solicitud. Acepta el workspace y, opcionalmente,release: el conjunto es una propiedad de esa raíz del workspace y de los directorios de catálogo que configura o, conrelease, de los directorios que la configuración asigna a esa Release; consulta Responder en los términos de una Release. Abarca los dos lugares de los que procede una entidad (los documentos de Aggrega bajo la raíz del workspace y las Features que contienen los directorios de catálogo configurados), porque esta es la superficie con la que un cliente hace el join cuando necesita los campos descriptivos de una entidad, y un índice que conociera solo uno de los dos dejaría sin resolver parte de cada lista de candidatos. Un documento del workspace cuenta como entidad cuando declara tanto unkind:como unmetadata.namey no declara ningunaapiVersionque pertenezca al grupo de otro proyecto, de modo que el YAML que se encuentra por casualidad en el árbol (el archivo de valores de un chart, una configuración de CI, un manifiesto de Kubernetes renderizado) se omite en lugar de listarse. Un documento que no declara ningunaapiVersionse notifica: es un documento de Aggrega al que le falta un campo, y verlo listado es la forma en que descubres que está ahí para corregirlo. Consulta Cómo se direcciona una entidad para saber qué significanoriginy unfilevacío. No se lee ningún documento que esté detrás de un enlace que lleva fuera de la raíz del workspace: un directorio fuera de la raíz no se explora, y un archivo fuera de ella no se lee declare lo que declare, de modo que una entidad que tu editor muestra bajo un enlace así no se lista como propia del workspace, ni la ofrecenaggrega/attachCandidatesniaggrega/connectionCandidates, que leen los mismos documentos, aunque tu editor tenga ese documento abierto. Eso se cumple declare lo que declare el documento. La única excepción es una Release que nombra la configuración de tu workspace (comobuild.authoring_releaseo como clave deworkspace.releases, juzgada por el archivo al que lleva el enlace, de modo que nombrar el enlace o ese archivo cuenta igual), que se lee desde el archivo al que lleva el enlace, se lista en la ubicación propia del enlace, tal como la listaaggrega/releaseCandidates, y no se nombra; un archivo nombrado por uno de esos ajustes que declara algo distinto de una Release no se lista, y su enlace se nombra. Los directorios de catálogo configurados son la forma en que un workspace lee otras entidades guardadas en otro lugar, de modo que un enlace a un directorio que la configuración lista encatalog_dirs(para el workspace o para una Release) no se explora como los documentos propios del workspace y tampoco se nombra: la configuración lo ha alcanzado, y sus Features se listan desde el catálogo, como las de cada directorio de catálogo configurado. Las Features listadas desde los directorios de catálogo nunca incluyen una que esté detrás de un enlace que lleva fuera del directorio dentro del cual deben permanecer las lecturas de un directorio de catálogo (el workspace, para un directorio de catálogo dentro de él, o el propio directorio, para uno que la configuración nombra fuera de él), de modo que una entidad que la respuesta nombra como situada detrás de un enlace que no leyó nunca se lista además junto a ese nombre. La respuesta nombra cada uno de esos enlaces enunreadLinkedDirs, para un enlace a un directorio, y enunreadLinkedFiles, para un enlace cuyo propio nombre termina en.yamlo.ymly que lleva a un archivo (en relación con la raíz, donde se encuentra el enlace, en el orden en que se explora el workspace), para que un cliente pueda explicar el motivo. Un enlace que la búsqueda deja fuera, por su nombre, por su ubicación o por un.gitignore, no se nombra, y en una respuesta en los términos de una Release tampoco uno situado bajo un directorio de catálogo que solo leen otras Releases. Un enlace bajo un directorio de catálogo situado fuera del workspace no tiene una ubicación relativa a la raíz en la que nombrarse, y no se nombra. Ambos campos están siempre presentes, y vacíos cuando no hay ningún enlace de ese tipo. Cuando el propio archivo de configuración del workspace, o el overlay gestionado por la CI junto a él, es a su vez un enlace que lleva fuera del workspace, ese archivo se nombra enunreadLinkedFilesindependientemente de cómo lo trate la búsqueda, y el índice es la lectura propia del workspace sin nada configurado: no se lee ningún directorio de catálogo para él, y un índice en los términos de una Release se rechaza; consulta Raíz del workspace y Release activa.aggrega/entityDefinition— aquello en lo que se resuelve la entidad nombrada: sukind, su propionamey suversion, sudescriptiony supublishScopecuando los tiene, elfileen el que se declaró, laauthoredLengthdel texto escrito por el autor que hay detrás, y sudefinitioncomo documento YAML con la herencia ya aplicada.filese informa para cada kind, como una ruta que puedes abrir: relativa a la raíz del workspace para un documento dentro de ella, absoluta para uno fuera, según Cómo se escribe una ruta notificada. Está vacío en un caso: una entidad resuelta desde un registro no tiene en esta máquina ningún documento escrito que nombrar.authoredLengthresponde a una pregunta distinta (cuánto texto escrito por el autor conservó la resolución), y solo un Aggregate se sirve con texto de ese tipo, así que lee los dos por separado en lugar de como un par.namees la identidad de una entidad, escrita de la forma en que una entidad hace referencia a otra, y puede llevar un sufijo de versión. Esta es la única solicitud de aquí que parte de un nombre en lugar de un cursor, así que es la que debes hacer cuando ya sabes a qué entidad te refieres.releasees opcional y resuelve el nombre en los términos de esa Release; consulta Responder en los términos de una Release. Un nombre que no se resuelve en nada se rechaza en lugar de responderse con un documento vacío; consulta Distinguir los dos rechazos por nombre.namepuede ser en cambio una referencia de registro,oci://<host>/<repository>:<tag>, o@<digest>en lugar de:<tag>, y la respuesta es entonces la entidad publicada en esa coordenada, leída desde su registro, conpublishednombrando lo que se leyó; consulta Preguntar por una coordenada.aggrega/releaseClosure— el cierre de dependencias de una Release: qué entidades alcanza y en qué versiones resueltas, enentities,librariesyplugins, junto con las identidadesaggregateymanifesten las que se resolvieron sus dos punteros, losmappingDiagnosticsque haya generado la resolución y lasdeprecationsregistradas sobre lo que alcanzó — en su lockfile y en el registro de confianza de plugins que está a su lado, de modo que un plugin retirado adjuntado en un rol de veredicto se nombra igual que una referencia fijada retirada.releasees una ruta relativa a la raíz del workspace que nombra una Release dentro de ella, el mismo valor que aceptaaggrega/irGraph, rechazada en las mismas formas, y requiere un lockfile por el mismo motivo. No se renderiza nada. Sus entradas no nombran ningunasource: dicen de qué depende la Release, no qué hizo una ejecución, que es lo que informaaggrega/resolveDependencies. Consulta Un cierre no es el grafo, porque un cliente que ya recibe el grafo no tiene esto.aggrega/attachCandidates— qué Features pueden adjuntarse a un nodo: aquellas cuya aplicabilidad declarada satisfacen las etiquetas del nodo. Envía exactamente una coordenada.nodenombra un documento del workspace por sumetadata.name;graphNodenombra un nodo del grafo compilado derelease, por el id con el que ese grafo lo indexa;labelslleva directamente un conjunto de etiquetas y no nombra nada, para un cliente que ya tiene uno. La respuesta repite la coordenada para la que respondió (vacía cuando no había ninguna que repetir), incluyenodeLabels, los pares de etiquetas con los que se evaluó la coincidencia,labelSource, que indica de qué tipo de conjunto de etiquetas se trata, y cada candidato como elkind, elname, el archivo fuente y eloriginque lo direccionan. Devolver las etiquetas es lo que hace que la respuesta sea verificable por sí misma: un cliente puede explicar por qué se ofreció una Feature sin formarse su propia idea de las etiquetas del nodo, que es como la respuesta de un cliente y la del compilador acaban divergiendo. Para un nodo del grafo, las Features ofrecidas son las que alcanza la Release de ese nodo. Junto agraphNode,connectionnombra una conexión que traza el componente de ese nodo (susockety sualias), y la respuesta incluye entonces tambiénslots, cada slot que declara el socket de esa conexión con las Features que pueden ocuparlo, onoSlotReasondonde no se puede ocupar ninguno. Consulta Qué te dice una respuesta de candidatos de adjunción.aggrega/connectionCandidates— a qué puede conectarse la entidad nombrada.nodees elmetadata.namede una entidad, la misma coordenada queaggrega/attachCandidatesacepta con ese nombre. Consulta Qué te dice una respuesta de candidatos de conexión más abajo, porque las dos mitades de la respuesta no están igual de completas y la respuesta dice cuál es cuál.aggrega/insertionPoint— dónde corresponde, en un documento escrito por el autor, una nueva entrada bajo un contenedor nombrado, expresado de modo que un cliente la aplique sin analizar el documento por sí mismo.filenombra un documento que contiene el workspace, relativo a la raíz del workspace, absoluto o como su direcciónfile://; un documento fuera de la raíz, tal como está escrito o a través de un enlace que lleva fuera de ella (al archivo o a un directorio por el camino), se rechaza sea cual sea la forma en que se escriba su nombre, y tengas o no una copia de él;containeres la ruta estructural desde la raíz del documento hasta el contenedor en el que va la entrada, siendo cada elemento una clave de mapping o una posición de secuencia escrita en decimal. Esa ruta la proporcionas tú: el daemon lee la estructura propia del documento y nunca deduce dónde corresponde algo a partir de cómo se llama. Consulta Qué te dice una respuesta de punto de inserción, porque la posición por sí sola no basta para aplicar la edición.aggrega/attachmentContainer— a qué documento corresponde la adjunción de una Feature para un nodo, y a qué contenedor dentro de él.graphNodenombra un nodo del grafo compilado derelease, por el id con el que ese grafo lo indexa, y ambos son obligatorios: el id de un nodo es una clave del grafo de una Release y no significa nada sin ella. La respuesta incluyenode,fileycontainer: una lista de segmentos exactamente con la forma que aceptaaggrega/insertionPoint, de modo que el par se compone sin nada que deducir entre medias. Para una adjunción en una conexión que traza el componente del nodo, añadeconnectioncon susocket, sualiasy eldocument(aggregateorelease), y la respuesta nombra el contenedorfeaturespropio de esa conexión en ese documento. Consulta Qué te dice una respuesta de contenedor de adjunción, porquefileforma parte de la respuesta en lugar de ser algo que ya conoces.aggrega/connectionAtPosition— dentro de la entrada de qué conexión cae una posición en un Aggregate o en una Release, con la respuesta expresada en los términos en que las dos solicitudes anteriores aceptan una conexión.filenombra el documento de la forma en que lo nombraaggrega/insertionPoint, y se lee primero a partir de lo que la sesión tiene para él;positiones el lugar dentro de él, unaliney uncharactercontados desde cero en la codificación de la sesión;releasenombra la Release cuyo grafo compilado registra las conexiones, y es obligatorio también para una posición en el Aggregate, porque un nodo del grafo y una conexión solo existen en un grafo compilado. La respuesta incluyegraphNodeyconnection(susocket, sualiasy eldocumenten el que se leyó la posición) para pasarlos sin cambios aaggrega/attachCandidatesyaggrega/attachmentContainer, onoConnectionReasondonde no hay ninguna conexión escrita. Consulta Qué te dice una respuesta de conexión en una posición.aggrega/editDocument— aplica una edición estructurada y acotada a un documento escrito por el autor, conservando cada byte que no toca. Es la otra mitad de los dos métodos de localización anteriores: aquellos dicen dónde corresponde una entrada y te dejan componerla y aplicarla, y este compone una y la aplica.editindica cuál de las cuatro (add-component,attach-feature,wire-edge,set-value), y un valor fuera de ellas se rechaza en lugar de interpretarse;nodees la ruta estructural desde la raíz del documento, una lista de segmentos exactamente con la forma que aceptaaggrega/insertionPoint;namees la clave bajo la que se escribe la entrada yvaluelo que contiene, cuyo significado se deriva deedit;socketse lee parawire-edgey se ignora en los demás casos.dryRunhace todo lo que hace la solicitud simple salvo escribir, y responde con el documento editado comocontent, para un cliente que primero muestra el resultado al autor; con él no se crea nada ywrittenestá vacío.filenombra el documento de forma relativa a la raíz del workspace o por su ruta absoluta, y un documento fuera de la raíz (tal como está escrito, o a través de un enlace que lleva fuera de ella, al archivo o a un directorio por el camino) se rechaza sin leer ni escribir nada. Esto escribe el documento que nombras, dentro del workspace: no resuelve ninguna dependencia, no accede a ningún registro y no toca la red con ninguna de las dos formas de entrega, y la escritura está condicionada a que el documento compuesto se valide con el esquema de su propio kind. Consulta Qué te dice una respuesta de edición de documento, porque el comportamiento predeterminado es la escritura y un rechazo deja el archivo idéntico byte a byte a como estaba.aggrega/releaseCandidates— los documentos Release del workspace que nombró la solicitud, como rutas absolutas. Acepta el workspace y nada más: el conjunto es una propiedad de esa raíz del workspace. La pertenencia se decide por el kind del documento (elkind:del archivo esRelease) y no por el nombre de archivo, de modo que una Release nombrada sin un prefijo convencional se ofrece, y un archivo que simplemente se llama como una no. Esto es lo que debería listar el selector «¿qué Release?» de un editor, porque es el mismo conjunto del que elige la cascada de la Release activa que se describe más abajo. La respuesta también incluyelockfiles, que asigna cada Release listada (indexada exactamente por la cadena con la que la listareleases) a la ruta absoluta de su lockfile; está siempre presente, y es un objeto vacío cuando el workspace no contiene ninguna Release. También incluyeunreadLinkedDirs, que nombra (en relación con la raíz, donde se encuentra el enlace) cada enlace situado donde el listado leería un directorio y que lleva a un directorio fuera de la raíz del workspace: no se explora ningún directorio fuera de la raíz, de modo que una Release que tu editor muestra dentro de uno no se lista, y este campo es lo que permite a un selector explicar el motivo. Un enlace a un directorio que la configuración de tu workspace lista encatalog_dirsno se nombra: la configuración lo ha alcanzado, como directorio de catálogo y no como lugar donde se guardan Releases. Está siempre presente, y vacío cuando no hay ningún enlace de ese tipo. Junto a él,unreadLinkedFilesnombra del mismo modo cada enlace cuyo propio nombre termina en.yamlo.ymly que lleva a un archivo fuera de la raíz del workspace: no se lee ningún archivo de ese tipo, contenga lo que contenga, de modo que una Release alcanzada solo a través de uno de esos enlaces no se lista, y el paso de la cascada relativo a una única Release no la cuenta. La excepción es un archivo que la configuración de tu workspace nombra como Release (comobuild.authoring_releaseo como clave deworkspace.releases, juzgado por el archivo al que lleva el enlace, de modo que nombrar el enlace o ese archivo cuenta igual), que se lee y se lista en la ubicación propia del enlace, y no se nombra, siempre que declare una Release; uno que declara cualquier otra cosa no se lista, y su enlace se nombra. Está siempre presente, y vacío cuando no hay ningún enlace de ese tipo. Cuando el propio archivo de configuración del workspace, o el overlay gestionado por la CI junto a él, es a su vez un enlace que lleva fuera del workspace, ese archivo se nombra aquí independientemente de cómo lo trate la búsqueda, y el listado se lee sin nada configurado, de modo que una Release que la configuración habría nombrado a través de un enlace no se lista; consulta Raíz del workspace y Release activa. Consulta Dónde está el lockfile de una Release.aggrega/activeRelease— a qué Release apunta el workspace que nombró la solicitud, como ruta absoluta en un camporelease, para un cliente que decide qué seleccionar de forma predeterminada. Acepta el workspace y nada más. El campo está siempre presente, y un valor vacío significa que el workspace no apunta a ninguna: una respuesta correcta y no un error, de modo que un cliente que la actualiza en cada reinicio del daemon no se ve obligado a tratar un workspace corriente como un fallo. Cuando el valor está vacío, la respuesta también incluyereason, un resumen de una línea de lo que buscó la cascada, ytrace, el relato paso a paso; ambos se omiten cuando se resolvió una Release. Cuando se resolvió una Release, la respuesta incluye en su lugarlockfile, la ruta absoluta del lockfile de esa Release, que se omite cuando no se resolvió ninguna. La Release que nombra no tiene por qué ser una de las que listaaggrega/releaseCandidates(un marcador puede nombrar una Release en un directorio que ese listado deja fuera, comovendor/, o una nombrada sin extensión YAML), de modo que esta respuesta es donde un cliente lee el lockfile de la Release predeterminada. Consulta Dónde está el lockfile de una Release. Pregúntalo en lugar de deducir la respuesta a partir de una de las entradas de la cascada: una entrada que la cascada no acabó usando nombra una Release distinta de la que eligió. La respuesta se calcula cuando la pides, de modo que volver a pedirla después de escribir un marcador, editar la configuración o añadir un archivo de Release devuelve la nueva respuesta en lugar del workspace tal como estaba cuando se inició el daemon.aggrega/setActiveRelease— registra una Release como predeterminada del workspace que nombró la solicitud, escribiendo el marcador.aggrega/active-releasede ese workspace, y responde exactamente como respondeaggrega/activeReleaseuna vez escrito el marcador. Acepta el workspace yrelease: una ruta relativa a la raíz del workspace que nombra una Release dentro de ella, sujeta al mismo contrato que elreleasedeaggrega/irGraph: una ruta absoluta, una que sale del workspace y un valor vacío se rechazan, y también una que sale a través de un enlace, salvo que la configuración de tu workspace nombre esa Release. El marcador es una línea que nombra la Release en relación con la raíz, la forma que lee la cascada que se describe más abajo. Se escribe dentro del workspace y en ningún otro sitio: cuando.aggrega, o el propio marcador, es un enlace que lleva fuera del workspace (exista ya o no el lugar al que lleva), la solicitud se rechaza con el error invalid-params, cuyo mensaje es la frase propia de la condición precedida de su código corto,E0320: …(fatal-halts.md §«A path the operation writes leads through a link out of the directory it must stay inside (Una ruta que escribe la operación lleva, a través de un enlace, fuera del directorio dentro del cual debe permanecer)»), que nombra el enlace y adónde lleva, y no se escribe nada; a través de un enlace que permanece dentro del workspace sí se escribe. La respuesta nombra aquello en lo que se asienta la cascada en lugar de repetir lo que enviaste, y ambas cosas difieren cuandobuild.authoring_releasenombra una Release, ya que la configuración tiene prioridad sobre el marcador. Registra un valor predeterminado de esta forma en lugar de escribir tú mismo el archivo, para que el lugar donde acaba el marcador se juzgue según la regla a la que está sujeto cada archivo que el producto escribe en el workspace; consulta El límite del workspace.aggrega/effectiveConfiguration— la configuración vigente para el workspace que nombró la solicitud, y la capa de la que procede cada ajuste. Acepta el workspace y nada más: la respuesta es una propiedad de ese workspace.layerslista los archivos de configuración y las anulaciones de entorno que contribuyeron, empezando por la de menor precedencia;settingsincluye cada ajuste atribuido con su nombre con puntos, su valor efectivo y lasourceque lo determinó. Unasourcese escribe exactamente igual que la entrada correspondiente delayers, de modo que ambas se combinan directamente. Consulta Qué abarca la respuesta de configuración efectiva para saber qué capa nombra unasourcey cuáles son los límites de lo que significa una fila.aggrega/configInit— inicializa una configuración funcional registrando un registro y su política de confianza de firmas, para que una máquina nueva pueda descargar y verificar artefactos firmados sin editar YAML a mano.registryes opcional y un valor ausente inicializa el hub oficial, el mismo valor predeterminado que usaaggrega config init; elhostde la respuesta nombra el que se usó.globalyworkspaceson las anulaciones del destino de escritura, y enviar ambos se rechaza. Se niega a sobrescribir un archivo de configuración existente, nombrando el archivo: envíaforcepara continuar de todos modos, lo que fusiona la entrada del registro con lo que ya hay y conserva los demás ajustes.dryRunhace todo lo que hace la solicitud simple salvo escribir, y responde con la configuración inicializada comocontent, para un cliente que muestra el documento al autor antes de guardarlo; con él no se crea nada ywrittenes false. El rechazo por archivo existente se aplica también condryRun, así que envíaforcejunto con él para recibir como respuesta la fusión que produciría una escritura que sobrescribe. En un workspace sin conexión solo se puede inicializar el hub oficial: esta solicitud no acepta identidades ni clave, de modo que cualquier otro registro se rechaza exactamente como lo rechazaaggrega/registryAdd, código corto y frase incluidos, y se añade en su lugar mediante esa solicitud con una política proporcionada a mano. La respuesta incluyehost,scope,trustywritten, yexisted, true cuando el archivo de configuración ya existía (de modo que la entrada del registro se fusiona con él en lugar de crearse un archivo nuevo) y ausente cuando se crea el archivo. Esto escribe la configuración global de forma predeterminada; consulta Acceder a un registro y escribir.aggrega/configCapture— congela la configuración efectiva crítica para la compilación en el archivo de configuración propio de este workspace, para que el workspace se compile igual sin la configuración global de la máquina por debajo. No acepta ningún destino de escritura: la congelación existe para hacer autosuficiente un workspace, así que siempre escribe el archivo de ese workspace.allPluginsamplía el conjunto congelado desde los sockets que determinan la salida renderizada (los bindings de provider y las adjunciones de gobernanza de transformación de etiquetas) a cada socket de plugin, añadiendo los gates de gobernanza de veredicto y de linter y el socket de importación. La respuesta incluyeconfigFile,workspaceRoot,captured,socketsycatalogDirs. Consulta Qué deja una escritura de configuración, porque la respuesta nombra un documento que ahora existe y lo siguiente que hace un cliente es abrirlo.aggrega/skillsInstall— escribe la skill de Aggrega integrada en este binario en la carpeta de skills de cada asistente que nombra la solicitud, la misma instalación que realizaaggrega skills installen un terminal.agentsenumera los asistentes por identificador, los identificadores que informaaggrega/skillsList; un identificador indicado dos veces se instala una sola vez, y donde varios de los asistentes nombrados leen una misma carpeta compartida, la skill se escribe allí una sola vez. Una instalación de proyecto lo exige. Una solicitud conglobalque no nombra ninguno instala para los asistentes encontrados en esta máquina, como haceaggrega skills install --globalsin--agent— cada uno cuya carpeta de configuración está en el directorio personal, o cuyo comando está en elPATHdel entorno del daemon — y se rechaza sin escribir nada donde no se encuentra ninguno; no se pregunta nada, einstallednombra los asistentes para los que escribió. Singlobal, la skill va a la carpeta de proyecto de cada asistente dentro del espacio de trabajo que nombra la solicitud, nunca al directorio en el que se inició el daemon; conglobal: trueva a la carpeta por usuario de cada asistente bajo el directorio personal que nombra el entorno del daemon (HOME, oUSERPROFILEen Windows). Cada destino se comprueba antes de escribir nada, de modo que un rechazo deja cada carpeta como estaba: un identificador para el que no se conoce ninguna carpeta de skills se rechaza nombrándolo junto con los identificadores que existen, y un archivo en un destino que no lleva la línea de comentario que lleva cada copia escrita de la skill se rechaza nombrando su ruta. Una copia que lleva esa línea — una que escribió una instalación anterior, o una tomada del repositorio de skills publicado — se reemplaza, y así es como unaggregamás reciente actualiza la skill a su propia versión. Una carpeta de proyecto a la que se llega a través de un enlace que sale del espacio de trabajo se rechaza sin escribir nada, como cualquier escritura que hace el daemon en un espacio de trabajo — consulta El límite del espacio de trabajo. La respuesta llevaskill,installed— una entrada por carpeta escrita, en el orden en que se nombraron los asistentes, cada una con losagentsque la leen, lafolderabsoluta yreplaced— yscope. Conglobal, esto escribe carpetas que lee cada proyecto de la máquina — consulta Llegar a un registro, y escribir.aggrega/skillsList— las skills que incluye este binario y cada asistente para el queaggrega/skillsInstallpuede escribirlas, la lista que imprimeaggrega skills list. Recibe el espacio de trabajo y nada más, y no lee nada de él.skillslleva elnamey ladescriptionde cada skill;agentslleva elid, elnamey laprojectFolderde cada asistente — relativa a la raíz de un proyecto, que en esta superficie es el espacio de trabajo que nombra una solicitud — y lauserFolder, relativa al directorio personal, ambas separadas por barras, ordenadas por identificador. No escribe nada y no llega a nada.aggrega/pluginAdd— busca en el registro configurado un plugin de un tipo nombrado y lo añade a la configuración.typeyqueryson ambos obligatorios:typees uno deprovider,governance,linter,importerycli, yqueryse compara con los nombres de los plugins de ese tipo y debe resolverse exactamente en uno, de modo que una consulta que coincide con varios se rechaza indicando los candidatos en lugar de resolverse arbitrariamente.capabilitynombra la capacidad a la que sirve un bindingprovidery es obligatorio en ese caso;rolenombra el rol de una adjuncióngovernance(label-transform,ir-verdictorender-verdict) y es obligatorio en ese caso; cada uno se lee solo para su propio tipo y se rechaza en cualquier otro, porque un campo que en silencio no hiciera nada parecería haber funcionado.acceptCapabilitieses obligatorio paracliy confirma las capacidades declaradas de ese plugin: el comando de terminal obtiene esa decisión preguntando, y esta superficie no tiene a quién preguntar, así que quien llama la obtiene y la envía.globalyworkspaceson las anulaciones del destino de escritura, y enviar ambos se rechaza.dryRunhace todo lo que hace la solicitud simple salvo escribir, y responde con la configuración resultante comocontent; no se crea ni se modifica nada ywrittenes false. Aun así se consulta el registro y se resuelve la versión, porque la identidad en ese contenido es la identidad que habría fijado una escritura.dryRunse rechaza en el tipocli, en lugar de ignorarse: lo que registra la adición de una extensión de comando es el digest del contenido de los bytes que verificó, un registro que mantiene el compilador y no un contenido que alguien edita, y la adición almacena en caché esos bytes sobre la marcha, así que se escribe en lugar de devolverse. La versión se fija por ti: la consulta se resuelve en un plugin, y en la entrada se escribe la versión que la consulta nombra como<name>:<version>o, en su defecto, la versión publicada más alta del plugin; una versión nombrada que una retractación en la que confía este espacio de trabajo ha retirado se fija igualmente y la respuesta incluyewithdrawn: true. Esto accede a un registro, y una adición de tipoclique no nombra ninguno de los dos ámbitos escribe la configuración global; consulta Acceder a un registro y escribir. Consulta Qué te dice un cambio de plugin.aggrega/pluginRemove— elimina la entrada de un plugin configurado para que deje de participar.typees el mismo conjunto que acepta una adición, yqueryidentifica la entrada: el nombre corto del plugin, su referencia fijada o, paraprovider, la capacidad a la que sirve el binding. Ambos son obligatorios.globalyworkspaceson las mismas anulaciones del destino de escritura, rechazadas juntas del mismo modo. Una consulta que no coincide con ninguna entrada se rechaza en lugar de responderse como un éxito sobre una configuración sin cambios, de modo que nunca se le dice a quien llama que un plugin dejó de participar cuando no fue así, y una errata nunca elimina un plugin distinto. No contacta con ningún registro: una eliminación opera solo sobre el texto de la configuración. Una eliminación de tipoclique no nombra ninguno de los dos ámbitos escribe la configuración global; consulta Acceder a un registro y escribir. Consulta Qué te dice un cambio de plugin.aggrega/pluginSync— alinea los registros gestionados por la máquina de una entidad Plugin con su módulo: el conjunto de funciones host derivado de las importaciones propias del módulo y el espejo de comandos leído de la autodescripción del módulo. Ninguno de los dos registros se escribe a mano, porque ambos tienen su fuente de verdad en el módulo. Ambos campos son obligatorios y ninguno tiene valor predeterminado (los registros se derivan del módulo, así que una alineación que no nombra ninguno no tiene nada con lo que alinearse), y ambos son rutas relativas a la raíz del workspace, rechazadas cuando son absolutas o se resuelven fuera de ella, tal como están escritas o a través de un enlace. Solo cambian esos dos bloques: cada otro byte se conserva literalmente, comentarios, líneas en blanco y estilo de comillas incluidos, y un archivo que ya registra lo que implica el módulo se deja idéntico byte a byte y se notifica como sin cambios. Esto escribe el archivo de entidad que nombras, dentro del workspace, y no contacta con ningún registro. Consulta Qué te dice un cambio de plugin.aggrega/pluginGenCatalog— genera una entidad Plugin por cada invitado seleccionado, combinando los campos del contrato derivados de la autodescripción del invitado con un overlay por plugin escrito a mano.fromEmbeddedypluginson los dos modos de selección y se aplica exactamente uno: todos los invitados que incluye este binario, o un módulo en una ruta que indicas; indicar ambos, o ninguno, se rechaza en lugar de resolverse.overlayes obligatorio, y es un directorio de overlays confromEmbeddedo un único archivo de overlay conplugin— cuando hay varios, un overlay se asocia a un invitado por su identidad, y cuando hay uno solo no hay nada que asociar.outputDires obligatorio en ambas modalidades de entrega, ydryRunno exime de él: una ejecución de prueba cambia adónde va el contenido, no de qué archivo es contenido, de modo que cada documento devuelto sigue indicando la ruta a la que está destinado, y esa ruta se compone a partir de este directorio. Las tres rutas no se juzgan igual, y la distinción sigue lo que la generación hace con cada una.pluginyoverlayse leen, y ambos son archivos que tú seleccionaste — un módulo acaba en el directorio en el que lo compila su cadena de herramientas, y su overlay se escribe junto a él —, así que cada uno puede ser absoluto y se lee donde realmente está. EnoutputDirse escribe, así que es relativo a la raíz del workspace y se rechaza si es absoluto o si se resuelve fuera de ella, tal como está escrito o a través de un enlace — un directorio aún no creado bajo un directorio enlazado que conduce al exterior se rechaza igual que ese directorio. Volver a ejecutar sobre entradas sin cambios produce entidades idénticas byte a byte. Esto escribe las entidades generadas bajooutputDir, dentro del workspace, a menos quedryRunlas pida en su lugar como contenido. Consulta Qué te indica un cambio de plugin.aggrega/getSchema— el JSON Schema de un tipo de entidad o de contrato, leído de la copia compilada en el binario en ejecución.kindes el token de esquema en minúsculas con guiones —component,aggregate,release,recipe,ir,wasm-provider, etc. — y es opcional, porque selecciona cuál de dos preguntas estás haciendo. Si indicas un tipo, la respuesta contienekindyschema, el esquema como documento JSON en lugar de como cadena que contiene uno. Si no indicas ninguno, la respuesta contiene en su lugarkindsyentityKinds: qué tipos puedes indicar, con dos amplitudes.kindses cada token que se le puede pedir a este binario, en el mismo orden en que los imprimeaggrega get-schema --list.entityKindses el conjunto más reducido de tipos de los que un autor escribe un documento, y cada entrada contiene el tokenkindque hay que devolver, el valordocumentKindque va en el propio campokind:del documento yacceptedBy, que indica si la validación de una sola entidad, la publicación y la inspección por nombre aceptan un documento de ese tipo. Consulta Qué tipos puedes ofrecer a un autor antes de construir un selector a partir de cualquiera de los dos. La respuesta con el esquema y la enumeración nunca se combinan, de modo que en la respuesta se puede leer qué pregunta se respondió. Un token al que no corresponde ningún esquema se rechaza con todo el conjunto válido en el mensaje, de modo que una errata se corrige sin una segunda llamada. No toma nada del workspace, no contacta con ningún registry y no escribe nada, así que responde en un workspace que no contiene nada en absoluto — y eso es lo que lo hace útil para conectar la asociación de esquemas de un editor con el binario que el editor está controlando realmente, en lugar de con cualquier copia de los esquemas instalada en otro lugar.aggrega/scaffoldEntity— un documento inicial para un tipo de entidad: exactamente los campos que exige el esquema de ese tipo, con los valores fijosapiVersionykindya rellenados y un marcador de posición en todos los lugares donde se necesita un valor.kindes obligatorio y es el token de esquema en minúsculas con guiones —component,aggregate,release,recipe,manifest,feature, etc.;aggrega/getSchemasinkindindica qué tokens puedes enviar, y un token al que no corresponde ningún esquema se rechaza con ese conjunto en el mensaje, de modo que una errata se corrige sin una segunda llamada. Un cliente que ofrece al autor la elección de un tipo leeentityKindsde ese método, que es el conjunto de tipos de los que se puede escribir un documento.namees opcional e inicializametadata.namepara los tipos cuyo esquema lo exige. La respuesta contienekindyskeleton. Consulta Qué te da una respuesta de scaffold, porque la respuesta es un documento por escribir y no un documento que se haya escrito. El esqueleto se deriva del mismo esquema que devuelveaggrega/getSchema, de modo que ambos responden desde una única fuente. Si se envíaexampleen lugar dekind, el método escribe uno de los ejemplos ejecutables de la documentación en un directorio nuevo del espacio de trabajo, como haceaggrega scaffold --exampleen un terminal; si se envía sololist: true, responde con todos los ejemplos que hay y no escribe nada. Ambas formas necesitan el espacio de trabajo, así que una solicitud de cualquiera de ellas lo nombra enworkspaceRoot, y una que no nombra ninguno se rechaza.dirnombra el directorio nuevo relativo a la raíz del espacio de trabajo y, por defecto, es el nombre del ejemplo; un valor absoluto, o uno que se resuelve fuera de la raíz — tal como está escrito o a través de un enlace — se rechaza antes de leer nada, y un directorio que contiene algo se rechaza y se deja como está. La respuesta a un listado llevaexamples, cada uno con suname, sulevely susummary; la respuesta a una escritura llevaexample,dir,files— cada archivo escrito, relativo adir—,next, los comandos que la página del ejemplo da para construirlo, ausente donde no da ninguno, yversion, la versión de la documentación de la que se leyó el ejemplo. Los campos de dos formas enviados juntos —kindconexample,listconexampleokind,nameconexampleolist, odirsinexample— se rechazan antes de leer nada, con las palabras con las que los rechaza la herramienta del asistente. Una escritura obtiene el paquete de documentación donde la máquina no tiene ninguna copia que admita la propia comprobación de firmas del espacio de trabajo, y escribe dentro del espacio de trabajo — consulta Llegar a un registro, y escribir.aggrega/import— convierte la descripción de un origen externo en borradores de archivos de autoría de Aggrega, la misma conversión queaggrega importrealiza en una terminal.sourcees obligatorio e indica el archivo o el directorio que se va a convertir, ya sea como ruta absoluta o relativa a la raíz del workspace — una descripción exportada por otra herramienta está donde la hayas guardado, así que se lee donde realmente está y no solo dentro del workspace. Un directorio se lee como lo leeaggrega import: limitado a los archivos que seleccionan los patrones de archivo declarados por el importador, excluida la carpeta de salida de compilación del workspace,dist/, y confinado a sí mismo dondequiera que esté, de modo que no se sigue hacia fuera ningún enlace que contenga.outputDires opcional e indica el directorio al que van los borradores, y no sigue ese contrato: en él se escribe, así que es una ruta dentro del workspace, y un valor absoluto, o uno que se resuelve fuera de la raíz — tal como está escrito o a través de un enlace, incluido un directorio aún no creado debajo de él — se rechaza. Si lo omites, los borradores van bajo la raíz del workspace, donde los escribeaggrega importcuando no indica ningún destino — también condryRun.formatindica explícitamente el formato del origen; si lo omites, el formato se reconoce por las firmas que declaran los importadores — tanto los del catálogo del workspace como los importadores principales del compilador —, y un origen que ninguno reconoce, o que reconocen importadores de más de un formato, se rechaza pidiendoformaten lugar de adivinarse.targetindica una capability de provider, comocomposeohelm— la palabra a la que se vincula elspec.capabilityde una Recipe — y genera como borrador, junto a los borradores del importador, el Manifest sobre el que se construye la Release en borrador para ese provider, exactamente como lo haceaggrega import --target:manifest.yaml, que asigna cada tipo de componente y cada tipo de funcionalidad que necesitan los borradores — incluidos los tipos de un Aggregate del catálogo que compone el que está en borrador — a la Recipe o a la receta de funcionalidad de esa capability que el catálogo del workspace ofrece para él, por su nombre calificado por la capability y sin versión: la única que hay o, entre varias, la que lleva el nombre del tipo. Elspec.manifestde la Release apunta a él; un tipo sin ninguna, o con varias y ninguna con ese nombre, queda sin asignar con un hallazgowarnque lo nombra, y una asignación que el propio importador generó se conserva donde el catálogo la ofrece para ese tipo y esa capability, y en caso contrario se descarta con un hallazgowarn. Untargetal que no se vincula ninguna Recipe del catálogo se rechaza antes de que se ejecute el importador, nombrándolo junto con las capabilities a las que se vinculan las Recipes del catálogo, y no se escribe nada; si lo omites, no se genera ningún Manifest — salvo consync, que genera el borrador para el destino que nombra el registro de la importación anterior. Un importador principal que la máquina aún no tiene se descarga en la primera importación que lo necesita — consulta Qué te indica una respuesta de importación.dryRunhace todo lo que hace la solicitud simple excepto escribir, y responde con los borradores como contenido, para un cliente que los muestra primero al autor; en este modo no se crea nada ywrittenestá vacío.syncactualiza respecto al origen lo que una importación anterior generó enoutputDir, modificando solo lo que escribió la importación, como lo haceaggrega import --sync; sin él, se rechaza una solicitud cuyos borradores sobrescribirían un Aggregate ya existente. La respuesta contieneformat,outputDir,written,files,drift,diagnostics,decisionsyhalted. Consulta Qué te indica una respuesta de importación, porque un origen que el importador no pudo convertir por completo es una respuesta correcta y no un error.aggrega/explainError— lo que el compilador declara sobre la condición que nombra un código, y las entradas publicadas que enseñan la corrección en la autoría.codees obligatorio y acepta cualquiera de los dos identificadores de una condición: el código corto que un diagnóstico lleva enshortCode, o el descriptivo encode. Es la expansión de un código que los diagnósticos de este canal ya llevan, y es la misma respuesta queaggrega explainimprime en una terminal. La respuesta siempre contiene la condición —shortCode,codeymessage—, porque esa parte está declarada dentro del binario y no necesita red;entriescontiene la guía paso a paso publicada, ynoteindica por qué falta, donde falta. Esto adquiere el paquete de documentación cuando la máquina no tiene ninguna copia que admita la propia comprobación de firmas del workspace — consulta Llegar a un registry y escribir. Consulta Expandir un código que llevaba un diagnóstico.aggrega/invalidate— una señal de invalidación de caché procedente del observador de archivos del editor.
Notificaciones:
$/cancelRequest— del cliente al servidor: detiene la solicitud en curso enviada con ese id. El daemon cancela el trabajo de esa solicitud; una operación detecta la cancelación en su siguiente límite de paso y no al instante, de modo que el trabajo ya iniciado continúa un momento. Cancelar un id para el que no hay nada en ejecución es una operación nula segura.$/progress— del servidor al cliente: lo que una operación larga está haciendo mientras lo hace, en el token en el que la solicitud pidió que se le informara. Solo se envía para una solicitud que llevaba uno. Consulta Seguir una operación larga.aggrega/shutdown— inicia un vaciado cooperativo: las solicitudes en curso terminan, las nuevas solicitudes se rechazan y luego el daemon finaliza.aggrega/publishDiagnostics— un conjunto de diagnósticos enviado por el servidor (usado para las advertencias de desviación del lockfile y para el estado al iniciar). Cada entrada lleva unsourceque nombra cuál de las capas de diagnóstico del daemon la generó:aggregapara un hallazgo sobre los documentos escritos,aggrega-buildpara un aviso que generó una build — cada aviso que generó, que es el mismo conjunto que imprimeaggrega build— yaggrega-lintpara un hallazgo sobre las convenciones de publicación, los mismos hallazgos que imprimeaggrega lint. El campo está siempre presente en cada entrada, de modo que un cliente puede agruparlas en lugar de mostrar una única lista indiferenciada, y nunca tiene que distinguir una fuente ausente de una de las capas. Un frame se envía para un archivo solo cuando su conjunto difiere del último que se comunicó a este cliente, de modo que una solicitud que recalcula los mismos hallazgos no envía nada; el primer frame de un archivo, y un frame que vacía el conjunto de un archivo, son ambos diferencias y siempre se envían.
Pedir al propio proceso que se detenga llega al daemon en las mismas condiciones. Una interrupción desde una terminal, o una solicitud de terminación de un supervisor o de un runtime de contenedores, inicia el vaciado que inicia aggrega/shutdown: las solicitudes en curso terminan, las nuevas solicitudes se rechazan y luego el daemon finaliza. Una segunda solicitud termina el proceso de inmediato. Un cliente que lanza el daemon puede detenerlo de cualquiera de las dos formas, y uno que lo detiene a través del protocolo y uno que le envía una señal obtienen el mismo vaciado.
Validación en vivo
En cada aggrega/validate, el daemon valida el búfer del editor contra el esquema del documento y devuelve diagnósticos que apuntan a la clave problemática — el mismo veredicto que daría una build, sobre contenido sin guardar. Una solicitud que no envía content pregunta por el archivo tal como está en disco; un content enviado vacío es un búfer vacío, no una solicitud del archivo. Un archivo enviado sin su contenido debe ser uno que el workspace contenga y que se pueda leer — un archivo fuera del workspace, uno al que se llega a través de un enlace que conduce al exterior o uno que no existe se rechaza con el código invalid-params. Las entidades de catálogo, los Aggregates, los Manifests y las Releases se reconocen por su apiVersion y su kind. Los dos documentos que no llevan tal encabezado — la configuración del workspace .aggrega-config.yaml y el lockfile de la Release que nombra la solicitud — se reconocen en cambio por el nombre de archivo, de modo que una clave basura o mal formada en cualquiera de ellos también se subraya en vivo. Los archivos que no son documentos de Aggrega — plantillas de charts de Helm, archivos de Compose, manifiestos de Kubernetes y archivos .lock de otros ecosistemas como Cargo.lock o flake.lock — no reciben diagnósticos; el daemon nunca informa sobre archivos ajenos.
Un marcador de posición aún pendiente se nombra en su clave, junto con lo que admite. Una entidad de catálogo de un tipo que aggrega validate comprueba como entidad individual también se lee en busca de los valores obligatorios que deja como cadena vacía, según la lectura que aplica ese comando, de modo que el daemon nombra cada marcador de posición que nombra el comando para los mismos bytes. Cada marcador de posición es una entrada: su message dice que la clave es un marcador de posición aún pendiente, su suggest dice qué admite el valor, y su keyPath lleva la ruta con puntos de la clave. La entrada ocupa el lugar del propio hallazgo del esquema para ese valor vacío, y cualquier otro hallazgo sobre el documento se informa tal como lo informa la comprobación del esquema. También se nombra un marcador de posición que el esquema admite vacío, aunque la comprobación del esquema no informe nada sobre él — capability e implements de una Recipe o una FeatureRecipe en borrador son los que encontrarás. Donde la comprobación del esquema también rechaza el documento, cada entrada lleva el código de esa comprobación, E0215, y donde lo acepta, las entradas no llevan código: los mismos identificadores que lleva el informe del comando para esos bytes. Una entrada se dibuja en la clave que contiene el valor vacío, en la línea en la que el comando la nombra — incluso en una clave cuyo propio nombre contiene un punto, como la etiqueta component.aggrega.ai/type, donde un hallazgo que la comprobación del esquema informa sobre esa clave se dibuja en la clave que la contiene —, y keyPath nombra la clave completa. Esto se cumple tanto si la solicitud nombra una Release como si no, porque es una pregunta que el documento responde por sí mismo, y a un documento que aún debe un valor todavía no se le pregunta por las convenciones de publicación: esa capa se vacía para él, como ocurre con un documento cuya forma rechaza el esquema.
Cada solicitud nombra la Release a la que se refiere, y el daemon no guarda ninguna propia. Las comprobaciones semánticas resuelven el cierre de dependencias de esa Release y leen el lockfile de esa Release para obtener sus pines — o, para una entidad de catálogo, leen los directorios de catálogo con los que se construye esa Release, como describe el párrafo siguiente —, de modo que dos solicitudes que nombran dos Releases reciben cada una respuesta sobre la Release que nombró. Nada se traslada de una a otra: no hay una Release seleccionada que cambiar, y cambiar la Release contra la que validas es un valor distinto en la siguiente solicitud, no algo que haya que decirle al daemon que olvide.
Una entidad de catálogo nombrada junto con una Release se comprueba como entidad individual, en los términos de esa Release. Un file que contiene un Component, una Feature, una Recipe, una FeatureRecipe o un Plugin, enviado con una release, recibe la comprobación que ejecuta aggrega validate <path> --release <release>, sobre el búfer sin guardar del editor: sus referencias — el Component que implementa una Recipe, una biblioteca a la que hace referencia un pilar — se resuelven a través de los directorios de catálogo que la configuración del workspace asigna a esa Release, de modo que un mismo archivo puede estar limpio en los términos de la Release que se construye con él y fallar en los términos de una Release cuyos directorios no contienen aquello a lo que hace referencia. Ese es el veredicto que dan la línea de comandos y la herramienta validate de aggrega mcp para la misma entidad junto a la misma Release y, como el suyo, no recorre ningún cierre ni lee ningún lockfile. Un hallazgo bloqueante es una entrada de error con las propias palabras de la comprobación y con sus códigos, dibujada en la clave que nombra en la entidad y, donde no nombra ninguna, en la clave kind: de la entidad, como describe Qué contiene una entrada de diagnóstico — a menos que una build ya informe de ese fallo en el archivo, en cuyo caso la entrada de la build es el único informe; un aviso que la comprobación genera al leer el catálogo es una entrada de advertencia que lo precede; una comprobación limpia sobre directorios que existen todos no devuelve ninguna entrada. Una aserción fallida — una que llama a fail, en la Recipe o en el Component que implementa — no es aquí un hallazgo bloqueante sino una entrada de advertencia, con las palabras de la comprobación y con sus códigos, cerrada con la frase A Release must satisfy this assertion before a build of it can pass., y dibujada donde estaría el hallazgo bloqueante: la aserción de una Recipe en la propia clave de esa aserción bajo assertions, la de un Component en la clave kind: de la Recipe. Como un hallazgo bloqueante, cede ante la entrada de una build que informa del mismo fallo en el archivo. La comprobación construye la entidad en torno a marcadores de posición y valores predeterminados del esquema en lugar de los valores que establece una Release, así que no puede distinguir una aserción que espera a una Release de una que está rota, y deja el veredicto a una build, que informa de la misma aserción como error (una aserción fallida es una advertencia). Un directorio que la configuración del workspace enumera para la Release y que no es un directorio — no existe nada allí, por ejemplo — detiene la comprobación: el archivo lleva una única entrada de error en lugar del veredicto de la comprobación, el rechazo que cada comando da a ese directorio, que nombra la entrada, el archivo de configuración y la línea que la enumera, y el ajuste (De dónde se leen las entidades locales). Una release que no nombra ningún archivo, o que nombra un directorio, recibe respuesta en el archivo con la frase con la que la línea de comandos la rechaza, en lugar de comprobarse en los términos del workspace. Lo que una build de una sola entidad no puede sustituir se juzga como lo juzga la línea de comandos, y lo que la línea de comandos deja de lado o no comprueba no produce aquí ninguna entrada — consulta qué no comprueba la corrección de una entidad individual y, para una Recipe cuya plantilla lee un valor que solo aporta una arista de la topología o una credencial adjunta, la corrección de una entidad individual. El propio Aggregate de la Release, un Manifest, una Release y una biblioteca no se comprueban de uno en uno, porque la comprobación de entidad individual no admite esos tipos; para ellos se mantienen las comprobaciones del cierre descritas más arriba. Un búfer que contiene contenido Workload se lee como YAML que no es un documento de Aggrega, porque ese contenido se escribe dentro del campo workload: de una Recipe o de una FeatureRecipe y se comprueba allí, donde está; la línea de comandos y la herramienta validate, cuando reciben un archivo Workload por ruta, comprueban su forma por sí sola.
Nombrar una Release es opcional, y la respuesta indica cuál de las dos cosas pediste. Si nombras una, obtienes todo lo anterior. Si no nombras ninguna, obtienes las comprobaciones que un documento responde por sí mismo — si se puede analizar, si su propia forma es admisible y, para una entidad de catálogo de un tipo validado como entidad individual, qué marcadores de posición aún debe —, sin resolver ninguna Release, sin recorrer ningún cierre y sin leer ningún lockfile; la respuesta lleva entonces checked: "document". Si nombras una Release, esa clave está ausente, porque esa respuesta es el veredicto completo del método y no tiene nada que matizar.
Lee la clave en lugar de deducir a partir de los diagnósticos, porque las dos respuestas pueden parecer idénticas. Un documento bien formado validado sin Release responde con una lista de diagnósticos vacía, que es exactamente lo que responde un veredicto completo limpio, de modo que checked es lo único que separa «no hay nada mal» de «no se examinó nada que necesite una Release». De la misma regla se sigue una consecuencia: un lockfile se reconoce por su correlación con la Release que nombra la solicitud, así que una solicitud que no nombra ninguna no reconoce ningún lockfile y no informa nada sobre él.
Un workspace que no contiene ninguna Release recibe respuesta en lugar de rechazo, y eso es lo que mantiene utilizable allí el resto del daemon. La validación es lo que llena la caché de análisis que lee cualquier otra operación sobre archivos, de modo que un repositorio solo de catálogo, un scaffold con un único Aggregate o un directorio de pruebas siguen obteniendo hover, autocompletado, ir a la definición, referencias, implementaciones y diagnósticos en caché. Rechazar se llevaría todo eso por delante, precisamente en los workspaces donde un cliente no tiene ninguna Release que nombrar.
Qué contiene una entrada de diagnóstico
Cada entrada se sitúa con line y column, ambos con base 1 en la codificación de posiciones negociada en el handshake, y añade end_line y end_column cuando abarca un token completo. message es el texto que un cliente muestra al usuario, severity lo clasifica, y source nombra cuál de las capas del daemon la generó, como se describe más arriba.
Las capas responden a preguntas distintas sobre un mismo archivo, de modo que una entrada de cada una puede estar en la misma línea sin que ninguna sea un duplicado de la otra: una dice que el despliegue no es correcto, otra que la entidad no se puede publicar. Un cliente que las mostrara como una sola lista informaría dos veces de un único problema, y leer source es lo que las separa.
Dónde se sitúa una entrada depende de aquello de lo que trata, no de qué capa la generó. Un hallazgo sobre algo que escribió el autor se sitúa en la clave bajo la que lo escribió, de modo que el editor lo dibuja donde corresponde la edición. Un hallazgo sobre la forma de la topología desplegada nombra un componente y una clave de entrega en lugar de una línea — esas son coordenadas en la topología desplegada, no en el documento —, así que se dibuja en la clave kind: del documento y, en su lugar, nombra sus coordenadas en el mensaje. Ambos tipos llegan a la capa aggrega-build, porque una build genera ambos. Un rechazo que una build generó durante el renderizado también llega a esa capa, en el documento al que apunta el propio rechazo — un Workload que no satisface sus comprobaciones, en la clave workload de su Recipe; la aserción fallida de una Recipe, en la propia clave de esa aserción; una entrada que la composición del grafo rechaza, en la clave bajo la que la escribió la Release o el Aggregate; y cada hallazgo de un rechazo que reúne varios, en su propio documento y su propia clave — y, cuando no apunta a ningún documento, en la clave kind: del Aggregate; Un rechazo generado durante el renderizado lo describe. Así que un cliente sitúa cada entrada por sus propios line y column y nunca deduce una posición a partir de la capa.
Un hallazgo que no nombra ninguna clave que contenga el documento se dibuja en la clave que da nombre al documento. Un hallazgo que las propias comprobaciones de un documento generan sobre lo que dice, el hallazgo de la comprobación de entidad individual, y un aviso o un rechazo que genera una build se dibujan cada uno en la clave que nombran; cuando no nombran ninguna, o nombran una clave que el documento no contiene, se dibujan en la clave kind: del documento, o en su metadata.name cuando no declara ningún kind:, y al principio del archivo solo cuando el documento no declara ninguno de los dos o no se puede analizar. Un documento suele empezar con un comentario — cada archivo de catálogo lleva un encabezado de licencia —, y una entrada dibujada en su primera línea quedaría sobre ese comentario y se leería como un fallo en él, mientras que la propia identidad del documento es una línea que escribió su autor. Una entrada sobre algo distinto de lo que dice el documento se sitúa al principio del archivo: una entrada Dependencies: sobre las dependencias de la Release, una etapa que se detuvo sin nombrar nada del documento, un lockfile desviado, una referencia que un renderizado tuvo que rechazar, una Release que no se cargó — y también una entrada aggrega-lint cuya regla no calculó ninguna línea. Cuando una posición se indica en lugar de dibujarse, un hallazgo que no nombra ninguna clave sigue sin tenerla: la respuesta de error de un rechazo que no nombra ninguna clave lleva solo el documento en su data.
En qué documento se publica una entrada se deduce de la misma regla. Una validación que nombra una Release responde sobre el Aggregate de esa Release, la propia Release, el documento de cada módulo que importa el Aggregate y el Manifest que nombra la Release. Un hallazgo situado en la Release — el rechazo de una entrada que la Release escribe en una de las conexiones de un componente, del dimensionamiento que da a esa conexión, de un adjunto que rellena o dimensiona allí, de una conexión que cablea, de una Feature que solo la Release adjunta a un componente o a un límite, o del infra que da a un adjunto — se publica cuando se valida el documento de la Release, en la clave de la Release que lo escribió, y en absoluto en el Aggregate. Un hallazgo situado en el propio documento de un módulo — el rechazo de lo que declara uno de los componentes del módulo, de un socket que cablean sus adjuntos, de sus valores o de los valores en sus propias conexiones — se publica cuando se valida el documento de ese módulo, en la clave que lo escribió allí, y en absoluto en el Aggregate. Un hallazgo sobre la tabla de correspondencias del Manifest — una entrada que asigna un tipo a una Recipe o FeatureRecipe que no lo implementa, una entrada cuyo pin de versión no se puede analizar, o un tipo asignado cuya cadena extends no se puede seguir — se publica cuando se valida ese Manifest, en la clave de la entrada de correspondencia a la que se refiere, y en absoluto en el Aggregate; cuando el texto abierto del Manifest no escribe esa entrada — una entrada que hereda mediante su propio extends, o una que eliminó una edición sin guardar —, el hallazgo se publica en la primera línea del Manifest. Cualquier otro hallazgo que genera la validación de esa Release se publica en el Aggregate, entre ellos los hallazgos a nivel de dependencias que no nombran ningún documento de tu workspace — una referencia o un plugin retirado, un Component o una Feature del catálogo cuya cadena extends no se resuelve o cuyo esquema no es válido, un plugin de gate con el que no coincide el registro de confianza, una instancia de componente que ninguna correspondencia resuelve, una Recipe o FeatureRecipe cuyo provider no puede renderizar un tipo de entrada que declara, y los avisos de solapamiento de pilares del esquema y de estrechamiento al extender. Así, un hallazgo sobre lo que escribió el operador aparece mientras la Release está abierta, uno sobre lo que declara un módulo mientras ese módulo está abierto, y uno sobre una correspondencia mientras el Manifest está abierto, sea cual sea la etapa de la build que lo generó; un editor que valida cada documento abierto contra la Release muestra cada uno allí. Una Release cuyas dependencias no se pueden resolver en absoluto no genera ninguno de esos hallazgos, y el fallo al resolverlas es una única entrada al principio del propio documento de la Release y de cualquier otro documento validado contra ella que el daemon reconozca, como describe Validación en vivo, y no compruebe como entidad individual — su Aggregate, su Manifest, una biblioteca, otra Release, la configuración del workspace —, con el prefijo Dependencies: y con el propio relato de la resolución sobre lo que la detuvo. En el propio documento de la Release, la entrada es ese relato y nada más. En cualquier otro documento, primero dice que el documento se comprueba contra esa Release y nombra la Release como la nombra una solicitud — Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved: seguido del relato —, porque nada en ese documento dice contra qué Release se comprobó: un editor que comprueba cada documento abierto contra la única Release seleccionada pone la entrada en documentos que no tienen nada que ver con esa Release, y el nombre es lo que te indica que la causa es la selección. Un archivo que el daemon no reconoce no lleva ninguna entrada de ese tipo, sea cual sea la Release nombrada con él.
Una respuesta contiene todas las capas presentes en el archivo, por mucho que haya avanzado la validación. La respuesta de aggrega/validate es el estado actual completo del archivo: lo que encontró esta validación, las entradas aggrega-build que una build, una vista previa o una solicitud de grafo publicaron en el archivo, y sus hallazgos sobre las convenciones de publicación, cada uno bajo su propio source. Una validación que se detiene en el búfer — uno que no se puede analizar, o un documento cuyo envoltorio rechaza el esquema — responde de la misma manera: informa de su propio hallazgo y deja en pie todas las entradas de build del archivo, porque no aprendió nada sobre la build. Así, un cliente puede sustituir lo que tiene para el archivo, capa por capa, a partir de cualquier respuesta.
Un fallo se informa una sola vez. La validación propia de un documento y una build pueden encontrar el mismo fallo en él: la comprobación de entidad individual renderiza una Recipe que también renderiza una build, la validación compone el grafo que compone una build, y una Release cuyas dependencias no se resuelven hace fallar a ambas. Mientras una build informa de un fallo así en un documento, la validación de ese documento no lo informa una segunda vez: una entrada aggrega que nombra la misma condición — el mismo code — que el rechazo de una build en el mismo documento, situada en el mismo intervalo o en ninguna clave propia — dibujada donde se dibuja una entrada que no nombra ninguna clave, o al principio del archivo — se omite de cada respuesta y de cada publicación para ese documento, y el informe de la build queda solo. El informe de la build es la entrada del rechazo en la capa aggrega-build; o, para aggrega/build, aggrega/buildPreview o aggrega/irGraph rechazados con 1004 porque una dependencia no se resuelve, esa misma respuesta — que nada publica — en el documento que nombra su data.file, si no su data.lockfile, si no la Release que nombró la solicitud, siendo la última de esas respuestas para una Release la que cuenta. La validación conserva lo que encontró: en cuanto ninguna build informa del fallo — la siguiente ejecución publica la capa sin él, la siguiente respuesta de build, vista previa o grafo para esa Release es cualquier otra cosa, o se conecta un cliente que no recibió ninguna respuesta 1004 de ese tipo —, la entrada propia del documento se vuelve a informar, y donde no se ha ejecutado ninguna build no se omite nada. Una entrada aggrega situada en una clave en la que no hay ningún rechazo de build se mantiene, incluso cuando nombra la misma condición, porque puede ser un segundo fallo de ese tipo del que la build no ha informado.
code es un código estable y comparable por máquina para lo que informa la entrada, de modo que un cliente puede ramificar según él sin comparar el texto del mensaje. Una sola clave lleva el código, lo haya asignado quien lo haya asignado, y source te indica de qué tipo es el que tienes, porque las capas nombran las cosas a partir de vocabularios distintos.
- En una entrada
aggrega— un hallazgo sobre los documentos escritos — el código es la cadena bajo la que está registrada la condición, escrita como el paquete declarante seguido de la regla en kebab-case. Es el mismo valor que un consumidor de Go lee conCodeOf, cuya forma y superficie comparable se describen en la referencia de centinelas de error. - En una entrada
aggrega-build— un aviso que generó una build — el código es el que asignó el punto que lo generó, y esta capa lleva avisos de dos vocabularios distintos porque una build genera avisos sobre dos tipos distintos de cosas. Un aviso sobre la forma de la topología desplegada lleva un código de clase, comounsupported-field, asignado dondequiera que se generara, ya sea un plugin de renderizado o el propio renderizado; un código de clase nombra una clase de aviso en lugar de una condición registrada, así que no tiene fila en la referencia de centinelas, y la referencia de advertencias describe la claseunsupported-fieldy el flag que la silencia. Un aviso sobre los documentos escritos — un nombre a una edición de distancia de uno declarado, un parámetro que nada lee — lleva la cadena bajo la que está registrada su condición, con la misma forma que una entradaaggregay con una fila en la referencia de centinelas. En cualquier caso, el código nombra qué es el hallazgo y no quién lo encontró, de modo que una misma clase te llega con un único código por muchos que sean los lugares que la generan, y leer el código en lugar de la capa es lo que te indica cuál de los dos tienes. El rechazo en el que se detuvo una build durante el renderizado es la única entrada aquí que no es un aviso, y lleva de la misma manera la cadena bajo la que está registrada su condición. - En una entrada
aggrega-lint— un hallazgo sobre las convenciones de publicación — el código es la identidad del hallazgo: la identidad de la regla que lo produjo o, para un hallazgo que no nombra ninguna regla — que un linter propio puede informar con un código propio —, ese código. Es el identificador queaggrega lintimprime en la fila del hallazgo, tras el código corto si lo hay, y el valor queaggrega lint --output jsonlleva para ese mismo hallazgo, comoruleId, o comocodepara un hallazgo que no nombra ninguna regla. Un hallazgo mantiene una sola identidad en todas las interfaces, de modo que un cliente que agrupa o suprime una regla en el editor agrupa y suprime la misma regla en la terminal. Cada regla del conjunto de reglas del linter de publicación que declara Aggrega está registrada como condición bajo esa identidad, así que figura en la tabla de todas las condiciones bajo el código corto queaggrega lintimprime al principio de la fila del mismo hallazgo y queaggrega lint --output jsonlleva en él comoshortCode. Una regla de un linter propio que Aggrega no declara no nombra ninguna condición registrada, y tampoco un hallazgo que no nombra ninguna regla, aunque su propio código reproduzca la identidad de una regla que declara Aggrega — así que ninguno de los dos figura allí. Las reglas se describen en la referencia deaggrega lint.
Sea cual sea la capa, la clave responde a una sola pregunta — qué es esto, en términos que una máquina pueda comparar —, de modo que una extensión del editor que resalta, agrupa o suprime una clase de hallazgos se basa en el código y sigue funcionando cuando cambia la redacción de un mensaje.
Fíjate en qué objeto lleva qué: esto es una cadena en una entrada de diagnóstico, distinta del code numérico de un envoltorio de error JSON-RPC descrito más abajo en Códigos de error. Una respuesta lleva uno u otro, nunca ambos en el mismo lugar.
La clave se omite cuando nada de lo que produjo la entrada asignó un código, y todos los tipos tienen ese caso. Un búfer que ningún analizador de YAML puede leer informa del propio texto del analizador y de ningún código, porque detrás no hay ninguna condición propia de Aggrega; una etapa que informa de un fallo sin nombrar una condición tampoco tiene ninguna que informar; y un aviso al que quien lo generó no asignó ningún código llega sin él. Así que trata code como opcional, igual que end_line y end_column, y ramifica según él solo cuando esté presente. Un código es lo que informa un diagnóstico y nunca lo que selecciona uno: ninguna solicitud admite un código, y escribir uno de vuelta en tu propio código te da una cadena en lugar de una forma de comparar.
El identificador que compara un programa y el que cita una persona
Una condición lleva dos identificadores, destinados a dos lectores distintos. code es el de arriba: calificado y con guiones, de modo que un programa que ramifica según él se lee como lo que significa. shortCode es la letra E seguida de cuatro dígitos — E0164 — y es el que una persona puede leer en voz alta, escribir en un cuadro de búsqueda o pegar en una incidencia. Ambos nombran la misma condición y ninguno es la abreviatura del otro.
Cuál usar depende de quién lee. Compara con code en tu extensión; muestra shortCode al autor. Una extensión que solo mostrara code dejaría al lector con un identificador pensado para un programa, y una que comparara con shortCode estaría comparando un número que no dice nada de la condición. Esa división es la razón por la que viajan los dos y no solo uno.
codeDescription es donde se publica la condición, llevado como { "href": … }, que es la estructura propia del protocolo para una referencia que se abre para saber más sobre un diagnóstico. Un editor que conoce el protocolo lo convierte en una opción «más información» sin que haya que enseñarle nada sobre Aggrega, y ningún cliente necesita una copia de las explicaciones. La dirección lleva a la lista publicada de todas las condiciones, donde la entrada de un shortCode nombra la condición y continúa con la guía paso a paso de la corrección en la autoría.
El texto explicativo en sí no está en la entrada, y es deliberado. Un diagnóstico se emite en cada edición, así que una explicación que viajara con cada uno volvería a publicar los mismos párrafos en cada pulsación de tecla para un lector que normalmente ya los ha leído. Un cliente que quiere el texto lo pide una vez, con aggrega/explainError más abajo; un cliente que puede seguir un enlace no necesita ninguno de los dos.
Ambas claves están presentes exactamente cuando la entrada nombra una condición registrada, y ausentes a la vez en caso contrario. Lo que las determina es lo que hay detrás de la entrada y no qué capa la publicó, así que lee las claves y no la capa:
- Una entrada que nombra una condición registrada lleva las tres.
shortCodese resuelve, y la referencia lleva a la lista en la que se resuelve. - Una entrada cuyo código nombra una clase lleva solo
code. La clase de un aviso de renderizado y la identidad de un hallazgo de convenciones procedente de un linter propio — una regla que Aggrega no declara, o el código que lleva un hallazgo que no nombra ninguna regla — son identificadores reales por los que puedes agrupar y suprimir, y ninguno de los dos es una condición registrada — así que no hay ningún número que citar ni nada en la dirección que los describa. Una referencia enviada de todos modos sería un enlace que abre una página que no trata del problema del lector, y por eso no se envía ninguna. Esta es la forma habitual en la capaaggrega-build, aunque un aviso de build que sí nombra una condición registrada lleva las tres como cualquier otro. En la capaaggrega-lint, la forma habitual es el conjunto completo: una regla del conjunto de reglas del linter de publicación que declara Aggrega es una condición registrada, así que su hallazgo lleva el mismoshortCodequeaggrega lintimprime al principio de la fila del hallazgo, y la referencia al lado. - Una entrada que no nombra nada no lleva ningún identificador.
Así, los tres casos se distinguen solo por las claves: sin code significa que no hay nada que nombrar, un code sin shortCode al lado significa un identificador que no se resuelve más allá, y el conjunto completo significa un identificador con un lugar donde informarse. Trata las dos claves nuevas como opcionales, igual que code, y ofrece al lector algo que abrir solo donde haya llegado codeDescription.
Expandir un código que llevaba un diagnóstico
aggrega/explainError convierte cualquiera de los dos identificadores de una condición en lo que el compilador declara sobre ella y en las entradas publicadas que enseñan la corrección en la autoría. Es la misma expansión que aggrega explain realiza en una terminal y que la herramienta explain-error realiza para un asistente, y las tres responden desde un único lugar, de modo que un código expandido aquí y el mismo código expandido allí son una sola respuesta y no tres que resultan coincidir.
code es obligatorio y admite cualquiera de los dos identificadores — el shortCode que llevaba un diagnóstico, o el code que lo acompaña —, porque un cliente que tiene uno de ellos no tiene forma de obtener el otro sin preguntar. Un valor vacío se rechaza indicando qué enviar.
La respuesta siempre lleva shortCode, code y message: los dos identificadores de la condición y la frase con la que empieza cada diagnóstico que la nombra. Están declarados dentro del binario, así que llegan sin red y sin caché, y eso es lo que permite responder incluso a un workspace que no contiene documentación. reference es la misma dirección que lleva el codeDescription de un diagnóstico, para un cliente que prefiere enviar a su lector a la documentación en lugar de mostrar el texto.
entries lleva la guía paso a paso publicada, cada entrada como el heading que la abre y el body que la sigue, en el orden en que la propia documentación los asocia a la condición. Se omite cuando no se pudo añadir la guía, y note indica entonces por qué: la página publicada aún no documenta ninguna entrada para esta condición, o este workspace no puede leer la documentación — la máquina no tiene ninguna copia, o solo una que rechaza la comprobación de firmas del workspace. En cualquier caso, la condición de arriba se mantiene — la respuesta no es un fallo, y un cliente muestra lo que llegó con la nota al lado. entries y note nunca llegan juntos.
Un código que nada resuelve se rechaza en lugar de responderse con una condición cuyos campos están todos vacíos, y cada rechazo indica de qué caso se trata: un código bajo el que no hay registrada ninguna condición, un número que nombró una condición en su día y nunca nombra otra, o un código que este binario no declara cuando la lista publicada no se pudo leer en absoluto — este último deja abiertas ambas correcciones, ya que una lista publicada para otra versión puede nombrar una condición que este binario no declara.
La documentación se lee del paquete almacenado en caché para el workspace que nombra la solicitud, adquirido en el primer uso cuando no está, que es lo único para lo que esta solicitud llega a un registry — consulta Llegar a un registry y escribir. No se escribe nada en el workspace. Ninguna validación lo desencadena: una expansión ocurre porque una solicitud la pidió, así que nunca se llega a un registry mientras se valida o se inspecciona un documento.
Convenciones de publicación, a petición y en cada edición
El daemon responde a dos preguntas distintas sobre una entidad del catálogo, y son las preguntas que aggrega validate y aggrega lint responden en la terminal: si el despliegue es correcto y si la entidad es publicable según las convenciones del catálogo. Una validación siempre responde a la primera. Responde a la segunda solo cuando la pides.
aggrega/lint la pide explícitamente. Envía entity para una sola entidad del catálogo, release para cada entidad que alcanza el cierre de dependencias de esa Release, o ninguno de los dos para comprobar cada entidad bajo los directorios de catálogo configurados: los tres ámbitos que tiene el comando. Enviar a la vez entity y release nombra dos sujetos distintos y se rechaza. La respuesta contiene checked, el número de documentos de entidad que cubrió la ejecución, y files, los hallazgos agrupados por el documento al que se refiere cada uno y ordenados por ruta, con las entradas de cada archivo en la forma de diagnóstico descrita arriba. halted indica si el propio veredicto de la ejecución rechaza la publicación.
No enviar ninguno de los dos comprueba el catálogo completo tal como lo hace aggrega lint sin argumentos. Un workspace cuya configuración no da directorios de catálogo de Release propios se comprueba una vez, sobre sus propios directorios, y la respuesta es la descrita arriba. Un workspace que nombra Releases bajo workspace.releases se comprueba una vez por cada Release que contiene, sobre los directorios que lee esa Release, y nunca sobre todos a la vez; así, las variantes de catálogo que se mantienen una junto a otra, una por Release, se comprueban cada una en los términos de la Release que las lee. La respuesta contiene entonces también passes, una entrada por pasada: releases, las Releases para las que se ejecutó, cada una relativa a la raíz del workspace, con las Releases que leen los mismos directorios compartiendo una entrada; catalogDirs, los directorios que leyó, escritos como files escribe una ruta, y vacío para una Release que no lee ninguno, lo cual se informa en lugar de hacer fallar a las demás; y los recuentos y los files propios de esa pasada, que son lo que indica para qué Release se encontró un hallazgo. checked, los recuentos y files que los rodean cubren todas las pasadas juntas, de modo que un cliente que no lee passes sigue leyendo la ejecución completa. Una ejecución en la que ninguna pasada tiene un directorio que leer se rechaza en lugar de responderse como un catálogo limpio.
Establece prePublish junto con entity para comparar esa entidad con su versión publicada anteriormente y clasificar respecto a ella el incremento de versión propuesto. Es el único modo aquí que alcanza un registro, y se ejecuta porque la solicitud lo nombró: lo que admite una operación que sale al exterior es que un llamador la haya pedido. Solo tiene sentido con entity, así que prePublish sin entidad se rechaza.
aggrega/lint no publica nada en la sesión. Responde sobre el sujeto que se le dio, y escribir sus hallazgos en la lista de problemas del editor reemplazaría lo que una validación publicó para archivos que la solicitud nunca cubrió. No se escribe nada en disco en ningún modo.
serve.lint_on_validate ejecuta las mismas reglas en cada validación, y está desactivado a menos que lo actives. Actívalo en .aggrega-config.yaml, en el workspace sobre cuyas entidades quieres el consejo:
serve: lint_on_validate: trueNo existe un flag para ello, porque la pregunta que responde trata del propio contenido de un workspace, y la persona que tiene esa pregunta es quien escribe el workspace y no quien lanzó el daemon. Con él activado, una validación de una entidad del catálogo publica también los hallazgos sobre convenciones bajo la fuente aggrega-lint; con él desactivado, el valor predeterminado, una validación informa solo de las capas de corrección y ningún hallazgo sobre convenciones te llega. Una sesión del editor no dice nada sobre si una entidad es publicable hasta que pides esa capa.
Tres cosas se cumplen en esa capa, diga lo que diga la clave. Solo se ejecuta el modo que lee contenido local, de modo que no se consulta ningún registro, no se descarga nada y no se escribe nada; la comparación previa a la publicación se alcanza enviando aggrega/lint con prePublish, nunca mediante una validación, porque una comprobación que se ejecuta en cada edición es exactamente donde no debe alcanzarse un registro. Las reglas se evalúan sobre el búfer que llevaba la solicitud y no sobre el archivo en disco, de modo que un nombre que corriges deja de informarse antes de que guardes. Y los hallazgos son orientativos: un documento que los provoca sigue validándose, y su Release sigue resolviéndose y renderizándose, así que añade una capa y nunca un rechazo.
La clave controla esa capa y nada más. aggrega/lint responde a lo que se le pregunte con cualquiera de los dos valores, porque un llamador que lo envía ha pedido la comprobación por su nombre.
Solo se comprueban los tipos que se publican en un catálogo, porque de eso tratan las convenciones. Los documentos que no son contenido de catálogo, entre ellos un Aggregate y una Release, se omiten, y también el YAML que no es en absoluto un documento de Aggrega. Eso es lo que mantiene una sesión en silencio sobre los documentos en los que un autor pasa la mayor parte de su tiempo.
Cómo se escribe una ruta informada
Cuando una respuesta nombra un documento que el daemon localizó por ti, una sola regla decide cómo se escribe esa ruta: relativa a la raíz del workspace cuando el documento está dentro de ella, y la ruta absoluta cuando no lo está. Eso abarca el file de una identidad de entidad, el file de una definición de entidad y el file por el que se indexa cada grupo en una respuesta de lint. Ambas formas son rutas que puedes abrir, la primera respecto a la raíz que indicaste y la segunda tal cual, y ninguna se deja nunca vacía por el lugar en el que está el documento.
La segunda mitad de la regla es lo que necesita un directorio de catálogo configurado. Un workspace puede apuntar a directorios de catálogo en cualquier lugar de la máquina, y un documento en uno de ellos es tan real como un documento bajo la raíz. La ruta absoluta es lo que lo nombra, y es la misma forma que aggrega lint y un diagnóstico que detiene la ejecución imprimen para ese archivo en una terminal; así, un archivo tiene un solo nombre, sea cual sea la superficie a la que preguntaste. Lo que no recibirás es una ruta que suba por encima de la raíz, que nombraría archivos distintos según desde dónde se leyera.
Qué forma te entregaron se puede leer en el valor: todo lo que tu plataforma lee como ruta absoluta es la segunda forma, y todo lo demás es relativo a la raíz del workspace. No necesitas comprobarlo para abrir el archivo (unir una relativa a la raíz y abrir una absoluta tal cual funcionan ambas cosas), pero un cliente que agrupa por documento del workspace puede distinguir las dos sin preguntar.
Lo que esta regla no abarca. Una ruta que envías se rige por el contrato propio de esa solicitud, indicado con la solicitud arriba y normalmente más estricto: un destino se rechaza a menos que sea relativo a la raíz del workspace y se resuelva dentro de ella, enlaces incluidos. La notificación aggrega/publishDiagnostics lleva su file en forma absoluta en todos los casos, dentro de la raíz y fuera, porque ese valor es el identificador que comparas con tus propios documentos abiertos y no una coordenada en el workspace: tu editor lo resuelve como una ruta del sistema de archivos. aggrega/releaseCandidates y aggrega/activeRelease nombran cada Release y cada lockfile por su ruta absoluta, como dicen sus propias entradas arriba. Y aggrega/irGraph lleva el grafo compilado tal como lo registró el compilador, reteniendo solo los valores que un autor declaró sensibles, de modo que cualquier ruta registrada dentro de él es la que registró el compilador, en la forma que fija el propio contrato del grafo, y no una que este protocolo compuso para ti.
Qué formas acepta un parámetro que envías
Lo que nombra una ruta, y no qué método la lleva, decide qué formas acepta ese parámetro. La entrada propia de cada solicitud arriba indica el contrato para los parámetros que acepta; lo que sigue es el contraste entre ellas, y por qué es un contraste y no una incoherencia que tengas que memorizar método por método.
Un parámetro que nombra un documento que ya tienes puede escribirse de tres maneras: relativo a la raíz del workspace, absoluto o como la dirección file:// que un cliente de language server envía para un documento abierto. Se trata del file o el uri de aggrega/validate, aggrega/diagnostics, aggrega/invalidate, aggrega/hover, aggrega/completion, aggrega/resolve, aggrega/findReferences, aggrega/findImplementations, aggrega/insertionPoint y aggrega/connectionAtPosition. Las tres nombran un mismo documento y reciben la misma respuesta, porque cada una se reduce a una única forma canónica en el límite de la solicitud antes de que nada la lea; así, un documento que validaste con su ruta se encuentra con su dirección, y viceversa, y la forma que envíes no cambia nada de la respuesta. Una dirección se lee como la ruta que nombra, con sus escapes de porcentaje decodificados, cuando su autoridad está vacía o es localhost; una que nombra otra máquina se lee como el recurso compartido de red de esa máquina en un sistema que abre allí un documento de esa manera, y no nombra nada que el daemon pueda abrir en ningún otro lugar. Una dirección que además lleva una consulta, un fragmento, credenciales o un puerto tampoco nombra nada que el daemon pueda abrir. Un valor que no empieza por file://, sean cuales sean sus mayúsculas y minúsculas, nunca se lee como dirección, y el rechazo de archivo no validado nombra el valor que enviaste, fuera cual fuera su forma. De ellas, aggrega/insertionPoint y aggrega/connectionAtPosition son las dos que leen el documento del disco cuando no tienes una copia, y solo responden para un documento dentro del workspace: uno fuera de la raíz (tal como está escrito, o mediante un enlace que sale de ella, hacia el archivo o hacia un directorio intermedio) se rechaza con cualquiera de las tres formas que lo nombre, y un documento dentro de la raíz recibe respuesta en las tres. Las otras ocho no leen nada del disco en la ruta que nombran (aggrega/validate toma los bytes del documento de content, y el resto responde a partir de lo que se validó), así que responden para un documento dondequiera que lo tengas, dentro del workspace o no, y no se sigue ningún enlace que nombren para leer un archivo. Un parámetro que nombra un documento que seleccionaste fuera del workspace es el mismo caso por la misma razón: el source de aggrega/import se lee donde realmente está, como dice su propia entrada. Ambas son excepciones al límite del workspace por su clase (un documento que el cliente mantiene abierto y un archivo que eligió una persona) y El límite del workspace explica por qué cada una lo es.
Un parámetro por el que el daemon debe localizar un documento dentro del workspace acepta una ruta relativa al workspace y nada más. release es el que hay que conocer (en aggrega/irGraph, y con el mismo contrato dondequiera que aparezca) y un valor absoluto se rechaza con el error invalid-params, que indica el contrato y luego nombra el fallo concreto. Las solicitudes que escriben dentro del workspace someten sus destinos a ese mismo contrato, como dice la entrada propia de cada una. Cada una de esas rutas se juzga después por adónde lleva, con una sola regla tanto si la solicitud la lee como si la escribe (la definición de interior que indica El límite del workspace) y una ruta que lleva fuera se rechaza con el error propio de esa solicitud, citando el valor tal como lo enviaste, sin leer ni escribir nada: igual un enlace a un archivo de fuera que un enlace a un directorio intermedio, y también una ruta aún no creada bajo un directorio enlazado que lleva fuera, que se rechaza por el enlace en lugar de escribirse, o de buscarse fuera e informarse como ausente. Eso abarca cada ruta que una solicitud nombra para que el daemon la lea (release dondequiera que aparezca, el entity de aggrega/lint, y entity, plugin, file y from de las solicitudes de publicación), de modo que una solicitud no puede leer a través de un enlace un archivo que los propios listados del workspace omiten, y cada destino: los directorios en los que escriben una generación, una importación y una build, la entidad junto a la cual aggrega/pin escribe su bloqueo, el archivo de entidad y el módulo que aggrega/pluginSync lee y reescribe, y el documento que edita aggrega/editDocument. Un release que nombra una Release que nombra la configuración de tu workspace es la única excepción, como dice la entrada de aggrega/irGraph.
Los dos difieren porque los fallos difieren. Un parámetro que nombra un documento que ya tienes deja una sola pregunta, qué documento, así que reducir tu forma a la canónica no pierde nada, y aceptar cada una tampoco te cuesta nada. Un parámetro que selecciona un documento de dentro del workspace no está en esa situación: en las bibliotecas de rutas que probablemente use un cliente, unir un valor absoluto a una raíz produce ese valor absoluto en lugar de un error. Así que un valor reparado en silencio haría que el daemon leyera (e informara hallazgos sobre) una ruta que el workspace nunca contuvo, y se te hablaría de un archivo que no existe. La respuesta es rechazar en lugar de reparar, porque un daemon que reparara un valor así dejaría a cada cliente que envía uno creyendo que el contrato es opcional.
Cómo se direcciona una entidad
Cada entidad que nombra una respuesta se direcciona de la misma manera: kind, name y file. Haz el join por esas tres con aggrega/catalogIndex para todo lo que quieras mostrar: es la superficie que lleva el conjunto descriptivo completo de una entidad (apiVersion, description y labels), de modo que una respuesta que solo necesita nombrar una entidad informa de las tres claves de direccionamiento y deja la descripción en un solo lugar. Una búsqueda por nombre como aggrega/entityDefinition repite los pocos campos descriptivos de los que trata su propia respuesta; el índice sigue siendo la superficie con la que hacer el join cuando quieres el conjunto.
Donde una respuesta puede nombrar entidades de más de un lugar, cada identidad lleva origin junto a esas tres claves. aggrega/catalogIndex y aggrega/attachCandidates lo hacen ambas, porque sus entidades proceden de los documentos del workspace y de los directorios de catálogo configurados. Una respuesta que se nutre de un solo lugar informa solo de las tres claves y de ningún origin, ya que una clave con un único valor posible no te dice nada: cada entidad que nombra una respuesta así es un documento del workspace, y su file es una ruta relativa al workspace que puedes abrir. Así que lee origin donde esté presente en lugar de exigirlo en todas partes; las tres claves son aquello por lo que haces el join en cualquier caso.
origin pertenece a una respuesta que enumera entidades, donde distinguir las poblaciones es problema del lector. Una respuesta por nombre como aggrega/entityDefinition no lleva ninguno: nombra la única entidad a la que se resolvió el nombre, así que no hay poblaciones que separar. Su propia viñeta arriba dice cuándo su file está vacío; no interpretes ese vacío a través de los valores de origin de abajo, que describen un listado.
origin dice de dónde leyó el daemon la entidad, y es lo que hace legible file.
workspace: un documento de Aggrega bajo la raíz del workspace.filees su ruta relativa a esa raíz, que es una ruta que tu cliente puede abrir.catalog: una entidad resuelta a partir de los directorios de catálogo configurados.fileestá vacío en este listado, y elnamees la dirección completa. Está vacío porque el listado informa de lo que enumeró la búsqueda en el catálogo, que es una identidad y no un documento, así que la entrada no tiene ninguna ruta que informar; no se trata de una ruta retenida por el lugar en el que está. Pide aaggrega/entityDefinitionel mismo nombre cuando quieras el documento: esa solicitud resuelve la entidad e informa de sufilesegún la regla anterior, de modo que un directorio de catálogo fuera de la raíz del workspace se nombra allí por su ruta absoluta.namees, de todos modos, la coordenada que usan un Aggregate, una Recipe y la búsqueda en el catálogo.
Lee los dos juntos en lugar de comprobar solo file. Un file vacío por sí solo no podría decirte si la entidad no tiene ruta en el workspace o si simplemente no se informó de ninguna; origin responde a eso directamente.
Donde una Feature es accesible de ambas maneras (la raíz del workspace es a su vez uno de los directorios de catálogo configurados, lo cual es una disposición habitual), se informa de ella una vez, como documento del workspace, porque esa es la copia cuyo archivo puedes abrir.
Qué te dice una respuesta de attach-candidate
aggrega/attachCandidates responde a una sola pregunta (qué Features admite este conjunto de etiquetas) y ofrece tres maneras de decir a qué conjunto de etiquetas te refieres. Envía exactamente una coordenada; enviar dos, o ninguna, se rechaza en lugar de clasificarse.
{node} direcciona un documento del workspace por su metadata.name y no necesita nada más. La coincidencia se evalúa contra las etiquetas que ese documento declara en metadata.labels, y la respuesta informa labelSource: "declared".
{graphNode, release} direcciona un nodo de un grafo compilado. graphNode es el id bajo el que el grafo indexa el nodo: el mismo id que lees de aggrega/irGraph, incluida la forma cualificada que lleva un nodo aportado por un subagregado. release es una ruta relativa a la raíz del workspace que nombra la Release cuyo grafo se debe construir, el mismo valor que acepta aggrega/irGraph. La coincidencia se evalúa contra las etiquetas finalizadas del nodo, y la respuesta informa labelSource: "resolved".
{labels} lleva el propio conjunto de etiquetas y no direcciona nada. Es la forma subyacente a las otras dos: la coincidencia es una función de un conjunto de etiquetas y de las Features disponibles, de modo que un cliente que ya tiene un conjunto de etiquetas no tiene nada que nombrar ni nada que esperar. Envía un objeto JSON de pares de etiquetas; la respuesta informa labelSource: "supplied" y un node vacío, porque esta solicitud no direccionó ninguno. Un objeto vacío es una coordenada (pregunta por un nodo sin etiquetas), mientras que omitir la clave por completo, o enviar null, no direcciona nada y se rechaza.
Las dos coordenadas por nombre están separadas porque sus espacios de identificadores se solapan. Un id de nodo del grafo y el metadata.name de un documento pueden ser la misma cadena y nombrar cosas distintas, de modo que un único parámetro que llevara ambos sería ambiguo, y un daemon que adivinara a qué espacio te refieres respondería a veces con seguridad sobre el sujeto equivocado. Decir qué pregunta estás haciendo es lo que elimina la ambigüedad.
labelSource te dice hasta dónde llega la respuesta, y los tres valores no son intercambiables. declared es una coincidencia sobre lo que un documento dice de sí mismo, que es lo que puede ver una lectura del código fuente. resolved es una coincidencia sobre las etiquetas con las que el nodo acaba realmente, que es contra lo que una build evalúa la aplicabilidad; así que una respuesta resolved es una afirmación sobre lo que decidiría una build, y una respuesta declared no lo es. supplied dice que el daemon no leyó ninguna etiqueta y comparó lo que enviaste; lo sólida que sea esa respuesta depende por completo de dónde procede tu conjunto de etiquetas.
Por eso un cliente que tiene un grafo debería enviar {labels} en lugar de un nombre. Las etiquetas finalizadas de un nodo son las etiquetas del tipo de componente al que se resuelve, no las de un documento que por casualidad comparte su id, y un attachment label-transform puede después añadirles, cambiarlas o eliminarlas; así que las etiquetas que deciden la aplicabilidad de un nodo no tienen por qué ser las que declara un documento concreto. Un cliente que dibuja un grafo ya tiene ese conjunto de aggrega/irGraph; devolverlo llega a la misma respuesta que da la coordenada {graphNode, release}, sin reconstruir el grafo para obtenerla. Devuelve un conjunto que el propio daemon informó (el de un nodo desde aggrega/irGraph, el de una entidad desde aggrega/catalogIndex) y tu idea de las etiquetas de un nodo no puede desviarse de la del daemon, porque el conjunto nunca salió de su propia respuesta. Si ensamblas uno tú mismo, estás planteando una hipótesis, que se responde con honestidad y no es una afirmación sobre ningún nodo que contenga el workspace.
Los candidatos proceden del workspace y del catálogo. Un workspace que guarda sus Features en un catálogo en lugar de en su propio árbol no tiene ninguna Feature local, y sus candidatos son en su totalidad origin: "catalog". Para un nodo del grafo, ambos se leen en los términos de la Release de ese nodo: las Features del catálogo son las que declaran los directorios de catálogo que la configuración del workspace asigna a esa Release, y los documentos propios del workspace se ofrecen excepto los que están bajo un directorio de catálogo que solo leen otras Releases. Por tanto, un workspace que guarda una variante de una Feature por Release ofrece al grafo de cada Release su propia variante y nunca la de otra, mientras que una Feature escrita junto a los catálogos, bajo ningún directorio de catálogo, se ofrece para cada Release. {node} y {labels} no nombran ninguna Release, así que se nutren de cada documento del workspace y de los catalog_dirs propios del workspace. Una Feature que no declara ninguna aplicabilidad es candidata para cada nodo (una declaración ausente no plantea ningún requisito), mientras que una cuya declaración no puede leerse no es candidata para ninguno, porque tratar un selector ilegible como satisfecho dejaría que una errata ampliara lo que ofreces.
Un nombre que no se resuelve es un error, no una lista vacía. Esas dos respuestas significan cosas distintas: un array candidates vacío dice que este nodo no tiene nada que pueda adjuntarse a él, e informar así de un nombre mal escrito presentaría una errata como una respuesta definitiva. El rechazo nombra el espacio en el que buscó, para que sepas si buscar un documento del workspace o un nodo del grafo. {labels} no tiene ese riesgo (no hay ningún nombre que escribir mal), así que un conjunto de etiquetas que nada admite vuelve como una respuesta correcta que lleva un array vacío, y una solicitud que el daemon no puede leer se rechaza igualmente antes de que se ejecute ninguna coincidencia.
La coordenada de nodo del grafo necesita un lockfile; las otras dos no. Construir un grafo significa resolver lo que alcanza la Release, así que esa vía rechaza con el error de lockfile ausente cuando no se ha generado ninguno, nombrando el comando que hay que ejecutar: la misma precondición que tiene aggrega/irGraph, por la misma razón. Direccionar un documento del workspace no construye ningún grafo, y suministrar un conjunto de etiquetas no construye nada en absoluto, así que ambas responden en un workspace que nadie ha preparado todavía.
Informa y nunca crea. El método no modifica nada, no escribe nada y no crea ningún attachment. Componer y aplicar cualquier edición corresponde al editor, que es donde están el búfer y el historial de deshacer.
Lo que resuelve depende de la coordenada, y las tres no son iguales. {node} no resuelve nada y no alcanza ningún registro ni la red: los candidatos proceden del workspace y de los directorios de catálogo, ambos ya en disco. {labels} resuelve aún menos: no busca nada, porque no hay nada que buscar. {graphNode, release} construye el grafo de la Release, así que resuelve el cierre de dependencias de esa Release de la misma manera que aggrega/irGraph: primero desde los directorios de catálogo locales y la caché de artefactos, y desde el registro configurado para una entidad que ninguno de los dos contiene. Las tres responden sin conexión para un workspace cuyas entidades son todas locales; solo la coordenada de nodo del grafo puede ir a buscar más allá.
Preguntar por una conexión
Una conexión que traza un componente puede llevar attachments propios, que rellenan los slots que su socket declara en el Component consumidor: por ejemplo, una credencial que el componente presenta a lo que alcanza la conexión. Envía connection junto a {graphNode, release} para preguntar qué puede ir ahí: socket es el socket de dependencia a través del cual está cableada la conexión y alias el nombre que lleva dentro de ese socket, ambos exactamente como los escribió el autor. Una conexión solo existe en un grafo compilado, así que connection junto a node o labels se rechaza, igual que una conexión que no nombra ningún socket o ningún alias, o una que el nodo no traza.
La respuesta es la respuesta de nodo del grafo más los slots de la conexión. candidates conserva su significado (las Features que pueden adjuntarse al propio nodo) y se añade slots, una entrada por cada slot que declara el socket, en el orden en que los declara el Component:
slot: el nombre bajo el que se escribe, en losfeaturesde la conexión, un attachment que lo rellena.selector,required,inject,sensitiveydescription: el slot exactamente como el Component lo declara en el socket, vacío o false donde no declara nada.selectores la restricción con la que se acotaron los candidatos, de modo que puedes explicar un candidato, o su ausencia, solo a partir de la respuesta.candidates: las Features que pueden rellenar este slot en esta conexión. Una build somete un attachment así a dos reglas, y se aplican ambas: la aplicabilidad declarada de la Feature contra las etiquetas finalizadas del nodo, a la que está sujeto cada attachment que lleva el nodo, y elselectordel slot contra las propias etiquetas de la Feature. Así que los candidatos de un slot están siempre entre los del nodo, acotados por el selector. Una Feature contra cuyas etiquetas no puede evaluarse el selector no se ofrece, porque una build la rechaza en lugar de admitirla.
Donde no se puede rellenar ningún slot, slots es una lista vacía y noSlotReason dice por qué. Lee el motivo en lugar de tomar una lista vacía por «ninguna Feature coincidió»: esa sería una respuesta distinta, y el motivo es lo que las distingue:
feature-created-connection: una Feature trazó la conexión, desde su propio bloque de dependencias. Un attachment solo se escribe en una conexión que traza un componente o la Release, así que aquí no va nada, declare lo que declare el socket.ad-hoc-socket: el socket es uno que el Component no declara. El autor lo nombró, lo cual es válido, y un socket no declarado no declara ningún slot.no-slot-declared: el Component declara el socket sin ningún slot.
noSlotReason está ausente dondequiera que exista un slot, y slots y noSlotReason están ambos ausentes de la respuesta a una solicitud que no nombró ninguna conexión; así, una solicitud que no nombra ninguna conexión recibe una respuesta sin ninguno de los dos campos.
document se acepta y aquí no cambia nada. Los slots son los del socket y los candidatos los de las Features, los mismos sea cual sea el documento en el que se escribe un attachment; adónde va es la respuesta de aggrega/attachmentContainer. Un valor distinto de aggregate o release se rechaza igualmente, porque un valor aceptado e ignorado le parece a quien lo envía un valor respetado.
Qué te dice una respuesta de connection-candidate
aggrega/connectionCandidates responde a dos preguntas a la vez, y solo una de ellas tiene una respuesta completa. Leer la respuesta como una sola lista filtrada lleva a equivocarse con la otra.
Cada socket informado lleva targets (los Components locales del workspace cuyas etiquetas declaradas satisfacen la restricción de etiquetas que ese socket declara sobre lo que puede satisfacerlo), más el selector a partir del cual se calcularon esos destinos, el flag required que declara el socket y declaration. targets es siempre un array, vacío en lugar de ausente, de modo que un socket que nada satisface se sigue informando como un socket que declara la entidad.
La mitad de los destinos es completa. El conjunto se decide evaluando la restricción declarada del socket contra las etiquetas declaradas de un candidato, la misma evaluación que realiza una build, así que lo que ofreces es lo que esa misma restricción admite durante una build. Un socket que no declara ninguna restricción deja sus destinos sin restringir e informa de cada Component: ese es el significado que el lenguaje de restricciones da a un selector vacío, no un error.
La mitad de los sockets es abierta, y declaration junto con adHocSocketsAccepted son la forma de saberlo. El autor de un Aggregate es dueño de su topología y puede cablear un socket que la entidad de catálogo del componente nunca declaró, así que los sockets que declara una entidad son un conjunto inicial útil y no el conjunto de nombres de socket válidos. Preséntalos como sugerencias, no como las únicas opciones: un selector de interfaz que solo ofreciera los sockets declarados le diría al autor que su libertad es más estrecha de lo que es.
declarationesdeclaredcuando la entidad direccionada enumera el socket en suusesSchema, yad-hoccuando no. Son los mismos dos valores que lleva una arista en el grafo IR, de modo que un único vocabulario responde a «de dónde salió este socket» dondequiera que encuentres la pregunta.adHocSocketsAcceptedinforma de si la superficie de la entidad direccionada acepta un socket que su propia declaración no enumera. No siempre es verdadero: la superficie de dependencias de un Component acepta uno, y la superficie de attachment de una Feature no, porque un attachment participa en la topología que declara la Feature adjunta en lugar de crear la suya propia. Un socket ad hoc en una superficie que no acepta ninguno se informa sin destinos, porque ninguna conexión a través de él se construiría.
Nombrar un socket en la solicitud limita la respuesta a ese único socket, y es la única manera de preguntar por un socket que la entidad no declara: un socket no declarado no aparece en ninguna declaración que enumerar. Omítelo para obtener cada socket que declara la entidad, en el orden en que están escritos.
Lo que informa es una coincidencia sobre etiquetas declaradas. Una build evalúa la restricción de un socket contra las etiquetas finalizadas del nodo del otro extremo de la arista, y esas son las etiquetas del tipo de componente al que se resuelve ese nodo, después de que cualquier attachment label-transform haya intervenido, no necesariamente las etiquetas del documento que nombraste. Así que una respuesta positiva aquí no es una promesa sobre lo que decidirá una build: es el mismo límite que tiene aggrega/attachCandidates con su fuente de etiquetas declared.
Informa y nunca crea. El método no resuelve nada, no alcanza ningún registro ni la red y no escribe nada: no crea ninguna arista y no propone ningún texto. Componer y aplicar la edición corresponde al editor, que es donde están el búfer y el historial de deshacer.
Para las identidades de entidad en targets (kind, name y file), haz el join con aggrega/catalogIndex como se describe en Cómo se direcciona una entidad. Los campos descriptivos se informan allí y deliberadamente no se repiten aquí, de modo que esta respuesta no lleva una segunda copia de ellos que pueda desincronizarse. Los destinos son Components del workspace, así que cada uno tiene un file que puedes abrir y ninguno lleva un origin: esta respuesta se nutre de un solo lugar, y el join es por las tres claves.
Qué te dice una respuesta de attachment-container
aggrega/attachmentContainer se sitúa entre las solicitudes de candidatos de arriba y el punto de inserción de abajo. Aquellas dicen qué puede adjuntarse a un nodo; esta dice en qué contenedor va un attachment para él, y en qué documento; la siguiente dice en qué lugar de los bytes de ese documento va el texto.
Pide el contenedor en lugar de componerlo. El id de un nodo y la ruta del subsistema que lo contiene se escriben ambos con puntos entre sus partes, y un punto es un carácter válido en un nombre que escribe un autor; así que desde fuera del documento no hay forma de distinguir un punto estructural de uno que está dentro de un nombre. Un cliente que ensamblara la ruta por su cuenta produciría algo que se lee correctamente y direcciona una clave que nadie escribió, y la edición que siguiera crearía esa clave en lugar de rechazarse. El compilador compuso ambas rutas, así que es el compilador quien las descompone.
Un id de nodo no lleva ningún rastro de su subsistema contenedor. Un componente escrito dentro de subsystems.billing.subsystems.payments se indexa en el grafo como ledger, exactamente como lo haría un componente de nivel superior, así que en el id no hay nada con lo que un cliente pueda trabajar, por muy cuidadosamente que lo divida.
La respuesta consta de tres campos.
noderepite el nodo del que trata la respuesta, de modo que un cliente con varias solicitudes pendientes empareja cada respuesta con su pregunta sin llevar un orden propio.filees el documento en el que se escribió el nodo, relativo al workspace. Forma parte de la respuesta en lugar de ser algo que ya sabes: un nodo aportado por un módulo importado se escribió en el documento propio de ese módulo con el nombre que el módulo le dio, así que tanto el archivo como el último segmento del contenedor difieren de cualquier cosa que nombrara la solicitud.containeres la ruta estructural desde la raíz de ese documento, como lista de segmentos:["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Cada nivel de un subsistema contenedor vuelve a estar bajo la clavesubsystems, que es como lo escribe el documento. Un componente que el autor escribió en el nivel superior nombra en cambio["spec", "components", "checkout", "features"], porque el ámbito en el que se compila un componente así no es uno que contenga ningún archivo.
Es una lista de segmentos y nunca una cadena unida, y esa es la razón de ser de la forma. Una ruta unida tendría que volver a dividirla quien la recibiera, lo que reintroduciría la ambigüedad anterior una llamada más tarde. Pasa la lista sin cambios a aggrega/insertionPoint como su container.
Lee estructura y nunca significado. La respuesta se deriva del documento en el que se escribió el nodo, del ámbito en el que está y del nombre que escribió el autor. No se extrae nada de cómo se llama un componente, de qué tipo lleva ni de lo que dice una etiqueta.
Informa y nunca escribe. El método no modifica nada y no escribe nada en ningún documento. No crea ningún attachment, no compone texto y no aplica ninguna edición; no decide qué puede adjuntarse, que es cosa de aggrega/attachCandidates.
Una solicitud que nombra un nodo que el grafo no contiene se rechaza en lugar de responderse. Los ids de nodo son las propias claves del grafo (léelos del grafo que devuelve aggrega/irGraph) y un nodo aportado por un módulo importado lleva un id cualificado. También se rechaza un nodo para el que el grafo no registra ningún documento: dónde va un attachment es un hecho sobre un documento, así que un nodo sin documento no tiene respuesta en lugar de tener una vacía.
Requiere un lockfile, por la misma razón que aggrega/irGraph: nombrar el contenedor significa construir el grafo de la Release, y un grafo construido a partir de bytes que nada avala se informaría exactamente igual que uno que se comprobó.
Un attachment en una conexión
Envía connection junto a {graphNode, release} (con su socket, su alias y su document) y la respuesta nombra el contenedor features en la entrada propia de esa conexión en lugar de en la del nodo. document es obligatorio aquí, porque cualquiera de los dos documentos puede contener un attachment en una conexión que trazó el Aggregate: el desarrollador escribe uno en la entrada de la conexión en el Aggregate, y el operador en la entrada por arista de la Release que le corresponde.
aggregatenombra la entrada de la conexión en el documento en el que se escribió el nodo:["spec", "components", "gateway", "uses", "models", "gpt", "features"]para un componente de nivel superior, con cada subsistema contenedor escrito nivel por nivel como arriba. Una conexión que trazó la Release no tiene ninguna entrada en el Aggregate, así que allí se rechaza.releasenombra la entrada por arista bajo la entrada propia de la Release para el nodo (["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"]), tanto si la Release ya escribe esa entrada por arista como si no. Donde no la escribe,aggrega/insertionPointinforma enmissingContainerKeysde las claves que aún hay que escribir.filees entonces el documento de la Release. Una Release que no escribe ninguna entrada para el nodo se rechaza: dónde se coloca el nodo le corresponde escribirlo al operador, y la respuesta no lo decide.
Una conexión que trazó una Feature se rechaza en cualquiera de los dos documentos, por el motivo que da feature-created-connection arriba. El nodo, el socket y el alias se comparan exactamente como están escritos, y una conexión que el nodo no traza se rechaza en lugar de responderse con una ruta. Todas las demás propiedades de arriba se mantienen sin cambios: la respuesta es una lista de segmentos, lee estructura y nunca significado, y no escribe nada.
Qué te dice una respuesta de connection-at-position
aggrega/connectionAtPosition es el paso previo a las dos solicitudes de conexión de arriba, para un cliente que tiene un lugar en un documento en lugar de un nodo en un grafo: por ejemplo, un cursor en la entrada de una conexión. Responde a qué conexión está escrita ahí, en las coordenadas que aceptan esas solicitudes, y se detiene.
La respuesta es una de dos mitades, nunca ambas.
graphNodeyconnection: el nodo cuyo componente traza la conexión, por el id bajo el que lo indexa el grafo compilado, y la conexión por susockety sualias, condocumentnombrando el documento en el que se leyó la posición:aggregatepara el Aggregate o un módulo que importa,releasepara la Release. PasagraphNode, el mismoreleaseyconnectionaaggrega/attachCandidatespara los slots que declara el socket de la conexión, y aaggrega/attachmentContainerpara saber dónde va un attachment en ella; el contenedor que nombra está dentro de la misma entrada en la que cayó la posición.noConnectionReason: por qué no se informa de ninguna conexión. El conjunto es cerrado:no-connection-entry: la posición no está en ninguna entrada en la que se escriba un attachment. Una conexión escrita como lista de destinos (db: [store]) y una que traza el propio bloque de dependencias de una Feature no llevan una entrada así, de modo que una posición en cualquiera de ellas también responde esto.feature-created-connection: la posición está en la entrada de la Release para una conexión que trazó una Feature, que no lleva ningún attachment por el motivo que da arriba la respuesta sobre slots. Una Release escribe una entrada así donde el bloque de dependencias de una Feature traza a través de un socket que también declara el Component consumidor; la entrada se construye tanto si no configura nada como si establece elinfrapor arista de la conexión.unknown-connection: la posición está en una entrada que la Release escribe para una conexión que el grafo compilado no contiene. Una Release que se construye puede contener una: por ejemplo, una entrada bajo un alias que nada traza y que no configura nada (sintarget, sininfra, sinfeatures), o una entrada para un componente que un interruptoractive:desactivó, cuyas conexiones salen de la build con él.
Qué entradas cuentan. En el Aggregate, cada conexión que traza un componente, en su entrada bajo el alias de la conexión en el documento en el que se escribió el componente (para un componente que aporta un módulo importado, el documento propio de ese módulo). En la Release, cada entrada por arista que escribe, tanto si la entrada traza su conexión como si configura una que trazó el Aggregate. Dónde está cada entrada es lo que registra el grafo compilado, así que si una clave es una conexión nunca se deduce de cómo se llama. Un componente que un interruptor active: desactivó no está en el grafo compilado, así que sus propias entradas en el Aggregate responden no-connection-entry, mientras que la entrada de la Release para una de sus conexiones responde unknown-connection.
Una posición en cualquier lugar dentro de una entrada está dentro de ella. La entrada va desde su clave de alias hasta la última línea sangrada bajo ella, de modo que una posición en el alias, en su target o dentro de sus features recibe la respuesta para esa conexión, y donde las entradas se anidan gana la más interna. Una posición en la propia clave de un socket, por encima de los alias escritos bajo ella, no está dentro de ninguno de ellos, tenga el socket un alias o varios, y tampoco lo está una posición en la sangría anterior a una clave de alias.
Qué documento es cuál se deduce de la Release. El archivo propio de la Release se lee para las entradas que escribe; cualquier otro archivo se lee para las entradas en las que el grafo registra componentes como escritos. Un documento del que el grafo de la Release no lee nada responde no-connection-entry en cada posición.
Informa y nunca escribe, y lee el documento como lo hace aggrega/insertionPoint: primero de la copia de la sesión y, si no, del disco, dentro del workspace, con los mismos rechazos para un documento que está fuera de él, es ilegible o no es YAML bien formado. Requiere un lockfile, por el motivo por el que lo requiere aggrega/attachmentContainer, y construye el grafo sin renderizar nada.
Qué te dice una respuesta de punto de inserción
aggrega/insertionPoint es la contraparte de las dos solicitudes de candidatos anteriores. Aquellas dicen qué puede adjuntarse o conectarse; esta dice dónde va el texto correspondiente en un documento concreto. Responde y se detiene ahí.
Tú nombras el contenedor; el daemon lo localiza. container es una ruta estructural desde la raíz del documento — ["spec", "components", "web", "features"] — y es tu declaración de dónde va una entrada de este tipo en un documento de este tipo. El daemon no deriva esa ruta de cómo se llama una entidad, del tipo que lleva ni de lo que parece significar. Lee los bytes que escribió el autor e informa qué segmentos de la ruta tiene ya este documento, las columnas en las que están sus entradas y la última línea que alcanza su bloque más interno. Así, saber qué clave sigue siendo cosa del llamador, y saber dónde van las entradas de esa clave en este archivo viene de aquí.
Para adjuntar una Feature a un nodo de un grafo compilado, el llamador no tiene que conocer esa clave por sí mismo: pide a aggrega/attachmentContainer el documento y el contenedor, y pasa ambos aquí sin cambios.
La respuesta es una posición de ancho cero más lo que tienes que escribir a su alrededor. file es el documento, relativo al workspace. container repite la ruta por la que preguntaste, de modo que un cliente con varias solicitudes pendientes empareja cada respuesta con su pregunta sin llevar un orden propio. position inserta en lugar de reemplazar: nada de lo que ya está en el documento se sobrescribe ni se desplaza.
precededByLineBreak— empieza el texto que escribes con un salto de línea. La posición está al final de la línea a la que sigue la nueva entrada, lo que es válido tanto si el archivo termina en salto de línea como si no, y no altera ningún byte ya escrito. Solo es false para un documento que no contiene nada tras lo que situarse, en cuyo caso se escribe desde el principio del archivo.missingContainerKeys— los segmentos de la ruta del contenedor que este documento aún no contiene, el más externo primero. Cada uno debe escribirse como una clave propia antes de que la entrada pueda ir dentro del más interno. Está vacío cuando la ruta completa ya existe.entryIndent— la columna en la que empieza la primera línea de la propia entrada, contada en espacios desde el inicio de la línea.indentStep— cuánto más se sangra cada nivel de anidamiento.indentStepMeasured— si ese paso se midió a partir del propio anidamiento de este documento. Cuando es false, el documento no presenta anidamiento que medir y el paso es un valor de reserva, de modo que un cliente que prefiera imponer el suyo sabe que puede hacerlo.entryShape—mappingosequence, deducido de lo que el contenedor ya contiene, yunknowncuando el contenedor aún no existe o no contiene nada.unknownno es un fallo: el documento no ha dicho qué forma toman sus entradas, así que esa elección es tuya.
Cómo aplicarla. Escribe un salto de línea donde precededByLineBreak esté establecido. Luego una línea por cada entrada de missingContainerKeys, la más externa primero, cada una formada por la clave seguida de dos puntos — la primera sangrada en entryIndent menos indentStep multiplicado por el número de claves que faltan, y cada siguiente indentStep más adentro. Luego la propia entrada, sangrada en entryIndent. Cuando missingContainerKeys está vacío, la entrada es la única línea que escribes.
Lee missingContainerKeys incluso cuando esperes que el contenedor exista. Una posición aplicada sin las claves que deben precederla produce un documento que ya no se puede analizar, y ese es el único fallo que esta respuesta no debe dejar leer como ausente.
position cuenta desde cero, a diferencia de la de un diagnóstico. Tanto line como character empiezan en 0, igual que los valores de posición con forma LSP que reutiliza este protocolo, mientras que line y column de una entrada de diagnóstico empiezan en 1, como se describe en Qué contiene una entrada de diagnóstico. Un cliente que alimenta una superficie a partir de la otra convierte entre ambas.
positionEncoding nombra las unidades en las que se mide character, y es la codificación negociada en el handshake. Se informa en la respuesta en lugar de dejarla implícita porque una posición cuyas unidades tiene que adivinar el llamador es una posición que no puede aplicar: desplazamientos medidos de una forma y aplicados a un búfer medido de otra corrompen el documento en el primer carácter fuera de ASCII.
Una solicitud que no apunta a un lugar donde pueda ir una entrada se rechaza en lugar de responderse. Cada uno de estos casos es un estado de la solicitud y no del workspace, así que vuelve con el código invalid-params estándar y un reintento no cambia nada hasta que cambien file o container.
- El documento no se nombró, no está dentro del workspace, no se pudo leer o no es YAML bien formado — un documento sin estructura no tiene ninguna posición que informar.
- La ruta del contenedor no nombra nada: no tiene segmentos, o uno de sus segmentos está vacío.
- La ruta atraviesa un valor que el documento contiene como escalar. No se puede añadir nada dentro de un escalar, y reemplazarlo sería una reescritura en lugar de una inserción.
- La ruta llega a una colección que el autor escribió en estilo flow. Añadirle una entrada reescribe bytes que el autor ya escribió en lugar de añadir una línea, lo cual es una edición y no una posición.
- La ruta direcciona una secuencia de bloque con algo que no es uno de sus índices. Las entradas de una secuencia se direccionan por posición, así que un nombre no alcanza nada en ella y no se puede crear ninguna entrada que lleve ese nombre.
Lee el búfer que tiene el editor, no solo el archivo en disco. La caché de análisis del daemon se consulta primero, de modo que una posición se informa respecto al contenido sin guardar cuando lo hay, y respecto al propio archivo cuando la caché no contiene nada para él.
Informa y nunca escribe. El método no modifica nada, no resuelve nada, no llega a ningún registry ni a la red y no escribe nada en ningún documento. No compone el texto de una entrada ni aplica ninguna. Componer y aplicar la edición corresponde al editor, que es donde están el búfer y el historial de deshacer.
Qué te dice una respuesta de edición de documento
aggrega/editDocument es la otra mitad del par anterior: aquellas dicen dónde va una entrada y te dejan componerla y aplicarla; esta compone y aplica una, y escribe. Ambas siguen disponibles, porque un cliente con un búfer sin guardar y un cliente que edita lo que está en disco quieren mitades distintas — un editor con su propio historial de deshacer coloca el texto por sí mismo, mientras que un cliente que prefiere que se edite el archivo a que le digan dónde editarlo envía esta.
Una llamada aplica una edición, y el conjunto de ediciones es cerrado. edit nombra cuál: add-component añade una instancia de componente bajo un contenedor de componentes, attach-feature adjunta una Feature a un nodo, wire-edge conecta una conexión dentro de uno de los sockets de dependencia de un nodo, y set-value establece un valor en un nodo. No existe ninguna edición que elimine, reemplace un bloque que ya escribiste, reordene algo o escriba literalmente bytes que tú proporciones — así que esto no es un escritor de archivos con un nombre más estrecho, y un valor fuera de los cuatro se rechaza en lugar de interpretarse. El rechazo enumera lo que puedes nombrar.
Nombras el nodo como una ruta estructural, exactamente como la aceptan las dos solicitudes anteriores. node es la ruta desde la raíz del documento — ["spec", "components", "web"] — y el contenedor en el que va la entrada se deduce de edit. Para add-component, la ruta nombra el propio contenedor de componentes, porque la entrada que se añade es el nodo. name es la clave bajo la que se escribe la entrada: el nombre de la instancia, el nombre del adjunto, el alias de la conexión o la clave del valor. value es lo que contiene esa entrada, y lo que significa se deduce de edit — la entidad que solicita la entrada, el nodo al que apunta una conexión o el escalar al que se establece un valor. socket se lee para wire-edge y se ignora en los demás casos.
Una ruta en lugar de un nombre, por la misma razón por la que la acepta la solicitud de localización: un nombre habría que buscarlo, y un nombre que apareciera en dos niveles dejaría al compilador decidir a cuál te referías. Así, un cliente que sabe qué nodo está editando lo dice, y un cliente que no lo sabe sabe que tiene una pregunta que responder antes de editar nada.
Todo byte que la edición no toca se conserva. El documento se analiza solo para localizar el contenedor y la línea en la que termina su bloque; la entrada se genera y se inserta a nivel de línea. Los comentarios, las líneas en blanco, el estilo de comillas, los escalares folded y literal, las expresiones de plantilla y la forma del salto de línea final se mantienen sin cambios, y el paso de anidamiento se mide a partir de la propia sangría del documento en lugar de imponerse — así una entrada queda en el estilo en el que ya estás escribiendo. La misma solicitud sobre el mismo documento produce los mismos bytes, de modo que un cliente puede comparar dos ejecuciones y una revisión lee una edición como un único diff.
El resultado debe ser un documento que podrías haber escrito tú, y de eso depende la escritura. El documento compuesto se valida contra el esquema de su propio tipo y solo llega al disco si la validación se supera. Una solicitud que produciría algo que el esquema de autoría rechaza vuelve como E0275 — the edit was refused because the resulting document would not be valid, and nothing was written (la edición se rechazó porque el documento resultante no sería válido, y no se escribió nada) — con la propiedad que el esquema no admitiría y su ubicación. El archivo queda byte a byte como estaba, así que una edición rechazada es indistinguible de una que nunca se intentó y puedes reintentar una solicitud corregida sobre el documento con el que empezaste. Por eso tampoco se repite aquí ninguna regla: pedir que un documento Release contenga un valor de desarrollador lo rechaza el mismo esquema que rechazaría el documento escrito a mano.
Lo que es admisible semánticamente no se decide aquí. Si un socket de dependencia es uno que el productor declara, o si se cumple la aplicabilidad de una Feature, corresponde a la resolución que realiza una compilación, cada una con sus propios informes. Así que puedes nombrar una conexión de la que esta solicitud nunca ha oído hablar, y un Aggregate puede definir un socket que su entidad de catálogo no declara de antemano; lo que puede consumirse a través de un socket sigue siendo cosa del productor declararlo. Ejecuta aggrega/validate nombrando una Release, o pide el grafo, cuando esa sea la pregunta.
La respuesta nombra lo que se colocó y lo que llegó al disco, y son preguntas distintas. content contiene el documento que produjo la edición en ambas modalidades de entrega. written nombra el archivo que llegó al disco, y está vacío con dryRun. container es la ruta estructural del contenedor en el que quedó la entrada, para que puedas localizar lo que acabas de añadir sin volver a deducir esa regla. createdContainers nombra los segmentos que esta edición escribió porque el documento no los contenía, el más externo primero — vacío en el caso habitual en que la ruta completa ya existía, y leerlo es la forma de distinguir una entrada añadida dentro de un bloque existente de una que creó su propio bloque. file y edit repiten lo que enviaste, de modo que un cliente con varias solicitudes pendientes empareja cada respuesta con su pregunta. written, container y createdContainers son siempre arrays, vacíos en lugar de ausentes.
Con dryRun no se crea nada. written está vacío, content contiene el documento que habría producido una escritura, y el archivo queda intacto — así un editor puede presentar el resultado al autor para que lo guarde, lo modifique o lo descarte. El comportamiento predeterminado es la escritura, porque el producto de la operación es un documento editado y una superficie que produce uno debe entregarlo: una solicitud que no dice nada sobre la entrega edita el archivo.
Todo lo demás que hace una escritura, lo hace también una ejecución de prueba. El documento compuesto se valida contra el esquema de su propio tipo en ambos casos, así que una edición que una escritura rechazaría se rechaza también con dryRun, nombrando la misma propiedad — lo que significa que el error que obtienes de una ejecución de prueba es el error que te habría dado la escritura.
Una entrada que ya existe y contiene lo que pediste es una operación nula — el documento vuelve sin cambios y no se escribe nada. Una entrada con ese nombre que contiene otra cosa se rechaza en lugar de reemplazarse, porque reemplazar lo que escribió un autor no es una de las cuatro ediciones.
Después de una escritura, el daemon vuelve a leer el documento. Lo que tenía para ese archivo se descarta y su vista a nivel de workspace se restablece, de modo que la siguiente solicitud de validación, hover, autocompletado o grafo se responde a partir de los bytes que produjo la edición en lugar de la versión que reemplazó. La propia edición lee el archivo en disco y no el búfer que tienes — a diferencia de la solicitud de localización anterior, que consulta primero el contenido sin guardar. Es deliberado: escribir desde un búfer sin guardar pondría en la página contenido que el autor no había guardado, con el pretexto de aplicar una sola entrada. Guarda el búfer y luego edita.
Una solicitud que no apunta a un lugar donde pueda ir una entrada se rechaza en lugar de responderse, con el código invalid-params estándar, y un reintento no cambia nada hasta que cambie la solicitud. El documento no se nombró, no está dentro del workspace, no se pudo leer, no es YAML bien formado o no declara ningún tipo contra cuyo esquema pueda comprobarse el resultado; edit no se nombró o no es uno de los cuatro; node no nombra nada, o uno de sus segmentos está vacío; no se dio ningún name; wire-edge no nombró ningún socket; set-value recibió un mapping o una secuencia donde corresponde un escalar; la ruta del nodo llega a un escalar o a una secuencia, o a una colección escrita en estilo flow, donde añadir una línea reescribiría bytes ya presentes en la página; o la ruta del nodo no llega a nada en el documento.
No resuelve ninguna dependencia, no llega a ningún registry y no toca la red en ninguna de las dos modalidades de entrega.
Qué abarca la respuesta de configuración efectiva
aggrega/effectiveConfiguration responde a dos preguntas: qué configuración se aplica en esta sesión y qué capa decidió cada ajuste. Es la misma respuesta que imprime aggrega config show --origin, calculada una sola vez e informada en ambas superficies, de modo que las dos no pueden discrepar sobre de dónde vino un ajuste.
Un source tiene una de cuatro formas. La ruta absoluta de un archivo de configuración — incluido el archivo global que lee un daemon iniciado como aggrega --config <file> serve, nombrado con la ruta que se le dio; una variable de entorno tras un prefijo env:, como env:AGGREGA_SIGNING_REQUIRED; un flag global escrito en la línea de comandos que inició el daemon, nombrado como el flag, como --offline para un daemon iniciado como aggrega --offline serve; o (built-in defaults) para un ajuste que ninguna capa establece. Las tres primeras aparecen literalmente en layers. Los valores predeterminados no, porque los valores predeterminados no son una capa que haya contribuido — son lo que se aplica donde ninguna capa se ha pronunciado.
Un ajuste se atribuye a la capa de mayor precedencia que lo establece, sea cual sea el valor que escriba esa capa. Un archivo de configuración que escribe el valor predeterminado integrado, o que repite un valor que ya establece un archivo inferior, es el archivo nombrado: es el que mantiene el valor. Un archivo establece un ajuste conteniendo su clave, incluido el compañero _append de una lista, y una variable de entorno al exportarse con un valor no vacío. El archivo de configuración que pertenece a tu pipeline nunca se nombra para una clave que ignora. aggrega config show --origin informa según la misma regla.
Se da cuenta de cada ajuste que declara el esquema de configuración, aunque no cada uno con una fila propia. El compañero aditivo _append de una lista se informa en la fila de la lista a la que añade, de modo que una capa que contribuye solo mediante el compañero se nombra en la fila de esa lista y el compañero no tiene fila. Un ajuste dentro de las entradas de una lista — la política de confianza de un registry, las entradas de un adjunto de plugin — queda cubierto por la fila de esa lista.
Dos límites más, cada uno de los cuales hace una respuesta más gruesa de lo que parece.
- Un ajuste de lista o de mapa se atribuye en su conjunto, a la capa de mayor precedencia que lo establece. La atribución por entrada no se registra, así que una lista formada a partir de dos capas informa solo de la de mayor precedencia, y una entrada aportada por una capa inferior no se distingue de una que escribió la capa superior.
- El requisito de firma se atribuye a la primera capa que lo activó, no a la última que lo mencionó. Ese ajuste se compone de modo que cualquier capa que lo active prevalece y ninguna capa posterior puede desactivarlo, así que la primera capa en activarlo es la que hizo que el valor efectivo sea el que es. Una capa que escribe
required: falseno activa nada, así que donde cada capa que lo menciona escribefalse, el ajuste informa(built-in defaults).
Cada valor informado es la resolución tomada cuando ese workspace se nombró por primera vez. Editar un archivo de configuración no cambia un valor aquí; reiniciar el daemon sí. Es deliberado — los valores son la configuración bajo la que se responde cualquier otra solicitud sobre ese workspace, y eso es lo que los hace comparables con la raíz y la capa de configuración que el handshake informó para él. Un cliente que muestra la configuración junto a un archivo que el usuario está editando debería decir cuál de los dos está mostrando.
La atribución de capas se calcula cuando la pides, sobre los archivos tal como están. Así, un archivo de configuración editado después puede mover un source mientras el valor que tiene al lado sigue tal como se resolvió. Las dos mitades responden a preguntas distintas — qué está en vigor y qué capa lo decidió — y solo la primera es fija. Reinicia el daemon para volver a sincronizarlas.
Informa y nunca escribe. El método no cambia ninguna configuración, no crea ningún archivo y no resuelve nada desde un registry ni desde la red.
Aquí no se sirve el contenido del archivo de una sola capa. La línea de comandos puede imprimir literalmente los bytes propios de una capa, con comentarios y formato conservados; este método informa la resolución en lugar de los bytes. Un cliente que quiera el texto de una capa tiene la ruta en layers y puede abrirla.
Qué deja tras de sí una escritura de configuración
aggrega/configInit y aggrega/configCapture producen ambos un documento de configuración, y ambos lo escriben. La respuesta nombra el archivo; abrirlo es tu siguiente acción, no un sustituto de la escritura. Ninguno de los dos te entrega contenido para que lo coloques tú, a menos que lo pidas expresamente, porque una capacidad cuyo producto es un documento que nunca se escribió es una capacidad distinta con el mismo nombre.
Los dos difieren en su alcance, y cada respuesta dice cuál. Léela antes de mostrar el resultado.
- La inicialización escribe, de forma predeterminada, la configuración compartida por todos los workspaces de la máquina. Un registry y las identidades en las que confías en él suelen ser los mismos dondequiera que trabajes, así que ahí va la entrada, a menos que la solicitud envíe
workspace: true.scopecontiene elconfigFileque se escribió ymachineWide, que indica si es el compartido — deducido del archivo al que se resolvió la escritura en lugar de lo que pidió la solicitud, de modo que una respuesta no puede describir un cambio a nivel de máquina como uno local. - La congelación nunca va más allá del workspace. No acepta ningún destino de escritura ni ninguna anulación: todo su propósito es hacer que un proyecto sea autosuficiente, así que siempre escribe el
.aggrega-config.yamlpropio de ese proyecto. Por eso su respuesta contieneconfigFileyworkspaceRooty no declara ningún scope — no hay alcance que indicar.
La inicialización rechaza en lugar de sobrescribir. Un archivo de configuración que ya existe se deja intacto y el rechazo lo nombra, porque la inicialización es para una configuración que aún no existe, mientras que la escritura compartida en la que delega fusiona por diseño. Envía force para escribir de todos modos; la entrada del registry se fusiona con lo que ya hay y los demás ajustes se conservan. Una solicitud rechazada no cambia absolutamente nada.
trust dice qué hizo la política anunciada por el registry, como resultados separados en lugar de como texto. pinned significa que el registry anunció una política y se adoptó, con identities contando las identidades. notAdvertised significa que se consultó al registry y no anunció ninguna, lo cual no es un fallo — la inicialización continúa, y reason dice qué hizo el endpoint. Un registry al que no se pudo llegar se informa también así, ya que no volvió ninguna política y la inicialización continúa igualmente, y lleva unreachable al lado cuando el propio fallo muestra que nunca se llegó al registry: su nombre no se resolvió, una conexión a él se rechazó o no se pudo abrir, o no se pudo establecer una conexión segura con él. Un registry que respondió — con un not-found o con un estado de error — nunca lleva unreachable, así que lee esa clave en lugar de las palabras de reason para distinguir un registry que no publica ninguna política de uno al que nunca se consultó. baseline significa que se fijó la baseline integrada del hub oficial porque no se adoptó ninguna política anunciada, con reason diciendo por qué; la entrada lleva una política, así que no hay nada que fijar a mano. Las dos claves responden a preguntas distintas, así que un hub al que se consultó y no anunció nada lleva ambas, y un hub en un workspace sin conexión — nunca consultado — lleva solo baseline, con reason diciendo que el workspace está sin conexión. Cualquier otro registry que no anuncie nada lleva solo notAdvertised, se inicializa sin política, y el consejo que sigue es fijar las identidades a mano; sin conexión, se rechaza en lugar de responderse. skipped significa que no se intentó ninguna obtención. Un cliente que tratara como error cualquier cosa distinta de pinned informaría de una configuración que funciona como si estuviera rota.
Con dryRun no se crea nada. written es false, content contiene el documento que habría producido una escritura, y el archivo al que está destinado ese contenido es scope.configFile. No se crea ningún directorio ni se toca ningún archivo, así que un editor puede presentar el texto al autor y dejar que lo guarde, lo modifique o lo descarte.
Una ejecución de prueba difiere de una escritura exactamente en un aspecto — no escribe —, así que realiza todos los rechazos que realiza una escritura. El rechazo por archivo existente es el que importa aquí: dryRun sobre un archivo de configuración que ya existe se rechaza, nombrando el archivo, exactamente igual que una escritura. Eso es lo que hace que la respuesta pueda usarse como predicado — si la ejecución de prueba rechaza, la escritura habría rechazado, por el mismo motivo y con el mismo mensaje. Envía force junto con dryRun para recibir en su lugar la fusión que produciría una escritura con sobrescritura, sin escribir nada igualmente. Se consulta al registry sobre su política de confianza anunciada en ambas modalidades de entrega, porque la política de ese contenido es la política que una escritura habría fijado.
Lo que informa una congelación es lo que escribió, no una descripción de ello. sockets enumera cada socket de plugin que se congeló con los adjuntos congelados en él; catalogDirs contiene los directorios de catálogo. Ambos son siempre arrays, vacíos en lugar de ausentes.
socketyfieldno son la misma cadena, y la diferencia no es estética.socketnombra el socket al que están vinculados los adjuntos;fieldes la clave bajo la que se escribieron en el archivo. Solo difieren para el socket de providers, que se escribe bajo una clave en plural — así que usafieldcuando remitas a un lector a una línea del documento ysocketcuando nombres el propio socket.- Cada adjunto contiene
uri,capability,functionyrole, presentes solo donde el adjunto tiene uno. Identifican el adjunto en lugar de reproducirlo por completo: las entradas opcionales que un adjunto recibe en el momento de adjuntarse se congelan literalmente en el archivo y no se repiten en la respuesta. El archivo es la copia de referencia. captured: falsees un éxito. Un proyecto cuya configuración no participa en una compilación no tiene nada crítico para la compilación que congelar, así que el archivo se deja como está y ambas listas vuelven vacías. Tratarlo como un error informa de un workspace sano como si estuviera roto.
De forma predeterminada solo se congela lo que determina los bytes de salida — las vinculaciones de providers y los adjuntos de gobernanza que transforman etiquetas. Los controles de veredicto de gobernanza y de linters y el socket de importación quedan fuera, porque están pensados para variar entre entornos y congelarlos llevaría los controles de un entorno a cada checkout. allPlugins: true amplía el conjunto a cada socket de plugin. La pertenencia es por adjunto, no por socket, así que un socket de gobernanza que contiene un adjunto de transformación de etiquetas y uno de veredicto aporta, de forma predeterminada, solo el primero.
Cada valor se congela en su valor efectivo — lo que resulta de combinar la configuración de la máquina y la del propio proyecto —, de modo que una vinculación que hoy procede solo de la configuración de la máquina se escribe en el proyecto y viaja con él. Los ajustes de herramientas a nivel de máquina, entre ellos la política de confianza de un registry, no son críticos para la compilación y se quedan donde están. Congelar dos veces sobre una configuración sin cambios reescribe los mismos bytes, así que un cliente puede ofrecerlo libremente: una segunda llamada deja el documento que tiene abierto un lector exactamente como estaba.
Qué te dice un cambio de plugins
Las cuatro solicitudes de plugins escriben todas de forma predeterminada, y se dividen según lo que escriben: dos cambian un archivo de configuración y dos producen documentos en el workspace. Dos de ellas — la adición y la generación — aceptan dryRun, que hace todo lo demás que hace la solicitud y no escribe nada. Lee lo que la propia respuesta dice sobre dónde quedó el cambio en lugar de deducirlo de la solicitud — en una de ellas, una solicitud que no dice nada sobre el alcance significa el alcance más amplio.
Una adición y una eliminación contienen ambas scope, deducido del archivo al que se resolvió la escritura. configFile es ese archivo, machineWide indica si es aquel a través del cual se resuelve cada workspace de esta máquina, y workspaceRoot nombra el workspace sobre el que se abrió esta sesión, de modo que una respuesta con alcance de workspace dice de qué workspace se trataba. machineWide se deduce del archivo resuelto en lugar de lo que pidió la solicitud, y eso es lo que impide que una respuesta describa un cambio a nivel de máquina como uno local.
🔴 Una adición de tipo cli que no nombra ni global ni workspace registra el comando a nivel de máquina. Una extensión de comando es una herramienta a nivel de máquina, así que sin anulación se escribe en el archivo de configuración global a través del cual se resuelve cada workspace de esta máquina — y el comando que registra pasa a ser un comando aggrega de nivel superior para cada proyecto de esa máquina, incluidos proyectos que nadie en esta sesión ha nombrado. Una adición provider, governance, linter o importer funciona al revés: estas definen la compilación de un solo proyecto, así que sin anulación van al .aggrega-config.yaml propio de ese proyecto. Una eliminación sigue la misma regla para los mismos tipos. Envía workspace: true para mantener local una extensión de comando, o global: true para llevar cualquiera de las demás al archivo compartido; enviar ambos se rechaza. El scope de la respuesta es en cualquier caso la declaración de referencia, y un cliente debería mostrarlo antes de actuar sobre el resultado.
Una adición nombra lo que se colocó, y exactamente uno de tres campos dice qué clase de cosa era. type repite el tipo para el que se añadió la entrada, y después: identity contiene la identidad de entidad sin más, fijada a una versión, para un adjunto governance, linter o importer; uri contiene la dirección de artefacto oci:// del plugin, junto con la capability a la que ahora sirve, para una vinculación provider; y reference contiene la referencia fijada cuyos comandos se registraron, para una instalación cli. Así, un llamador lee en la respuesta qué clase de adjunto se colocó en lugar de volver a deducirla del tipo que envió. Una eliminación repite type y query junto a su scope y nada más — no hay nada más que informar sobre una entrada que ya no existe.
Una adición contiene además written y, con dryRun, content. written es aquello en lo que se ramifica un cliente: true nombra un archivo de configuración que ahora está en disco y que el cliente puede abrir, y con dryRun es false y content contiene en su lugar el documento de configuración que habría producido la escritura. Los dos nunca son significativos a la vez, y el archivo al que está destinado content es scope.configFile, así que nada en la respuesta contiene una segunda copia de esa ruta — lo cual importa aquí, porque el archivo de un adjunto global es aquel a través del cual se resuelve cada workspace de esta máquina.
Un plugin sin ninguna versión publicada se rechaza en lugar de adjuntarse sin fijar. Una adición resuelve la consulta a un único plugin y fija su versión publicada más alta, de modo que la entrada que escribe lleva una versión. Un plugin cuyo repositorio no publica ninguna versión conforme se rechaza nombrándolo, y una versión que retiró una retracción en la que confía este workspace se omite en favor de la siguiente inferior.
Una versión que nombra la consulta se fija aunque haya sido retirada, y withdrawn lo indica. Una query escrita como <name>:<version> fija esa versión en lugar de la más reciente —en todos los tipos salvo provider, que se vincula solo por nombre y rechaza una versión—, y nombrar una versión es la anulación: donde una retractación en la que confía este espacio de trabajo la ha retirado, se fija igualmente y la respuesta incluye withdrawn: true, el hecho que aggrega plugin add indica con una línea retraction: en el terminal. withdrawn está ausente en cualquier otra respuesta, así que su presencia es toda la señal, y su ausencia no afirma que la versión no esté retirada. Donde no se pudieron leer los marcadores de retirada de una versión nombrada, withdrawn está ausente y retraction incluye unscreened, indicando por qué, igual que en una adición que no nombra ninguna versión y se encuentra con el mismo fallo; una adición que no nombra ninguna versión informa en cambio en retraction de lo que concluyó la comprobación de retirada sobre la versión que eligió.
Una alineación informa de si cambió algo, y ese es el campo sobre el que actuar. changed distingue una escritura de una alineación que encontró los registros ya correctos: un archivo sin cambios queda idéntico byte a byte, así que un cliente que tiene ese documento no tiene nada que recargar, y ejecutar la solicitud dos veces no informa de ningún cambio la segunda vez. entity nombra el archivo, hostFunctions contiene el conjunto derivado, y commands contiene el reflejo como valores en lugar de como la línea que imprime un terminal — cada entrada con un name, una description opcional y flags, cada flag con su name y sus shorthand, description, type y default opcionales. La escritura es atómica, así que un cliente que lee ese archivo mientras se ejecuta la alineación nunca observa un documento parcial.
Una generación rellena exactamente una mitad de su respuesta, y el propio dryRun de la respuesta dice cuál. De forma predeterminada se escriben las entidades y notices contiene lo que la generación dijo sobre las escrituras que realizó. Con dryRun no se crea ni se modifica nada: documents contiene cada entidad generada como el path al que está destinada y su content, de modo que un cliente puede ponerlas en su propio modelo de documento, donde son visibles antes de guardarse y pueden modificarse o descartarse. Las dos mitades nunca están rellenas a la vez, así que qué modalidad de entrega se ejecutó se lee en la respuesta en lugar de en lo que se pidió.
Dónde ESCRIBE una solicitud de plugins está siempre dentro del workspace que nombró esa solicitud; lo que LEE se decide campo por campo. Un destino absoluto, uno que sube fuera de la raíz y uno que sale de ella a través de un enlace se rechazan en lugar de resolverse — así una generación no puede crear entidades en un árbol sobre el que tu sesión nunca se abrió, envíe lo que envíe. Una ruta que una solicitud solo lee es una cuestión aparte, que se responde campo por campo en lugar de con una regla para todas: aggrega/pluginGenCatalog lee un módulo y su overlay desde donde los seleccionaste, porque un módulo que compilaste está en el directorio de salida de tu cadena de herramientas y negarse a leerlo allí sería negar la operación en su propio propósito. aggrega/pluginSync lee sus dos rutas dentro del workspace, porque esa solicitud trata sobre un archivo que el workspace ya contiene. Las solicitudes de localización anteriores aceptan una ruta absoluta por otra razón distinta — un documento que el cliente ya tiene abierto, nombrado con la grafía que tenga.
Una solicitud a la que le falta algo que la operación necesita se rechaza nombrando el campo que hay que enviar. Una adición o una eliminación sin type o query; una adición provider sin capability, o una governance sin role; una adición cli sin acceptCapabilities; una alineación sin entity o plugin; una generación que nombra ambos modos de selección o ninguno, o a la que le faltan overlay o outputDir. Cada una vuelve con el código invalid-params estándar, y un reintento no cambia nada hasta que cambie la solicitud. También se rechaza una eliminación cuya consulta no coincide con ninguna entrada, nombrando el tipo, la consulta y el archivo en el que buscó — ese es un estado de la configuración en lugar de la solicitud, así que lo que hay que corregir puede ser cualquiera de los dos.
No se pregunta nada de forma interactiva, y la única decisión que se le habría pedido a una persona llega en su lugar como un campo. El comando de terminal pregunta a quien esté mirando si acepta las capacidades declaradas de un plugin de extensión de comando. Nadie está mirando este flujo, así que obtener y enviar acceptCapabilities corresponde al llamador, y una solicitud que no lo contiene se rechaza indicando qué enviar, en lugar de instalar con un consentimiento que nadie dio. Un daemon que se inició sin los medios para instalar una extensión de comando rechaza de plano una adición cli, en lugar de informar de un éxito que no instaló nada.
Qué tipos puedes ofrecer a un autor
aggrega/getSchema sin kind responde qué tipos puedes nombrar, y responde con dos amplitudes porque un cliente necesita una distinta para cada tarea. Lee la que estás pidiendo.
kinds es cada token al que responde el binario. entityKinds es el conjunto de tipos de los que un autor escribe un documento. La lista amplia contiene la representación intermedia, el lockfile, la configuración del workspace y los contratos de los sockets de plugins junto a los tipos que escribes — esquemas reales, todos ellos, pero no documentos de los que alguien escriba un archivo. Así, la lista amplia es la que se usa para conectar la asociación de esquemas de un editor, y la estrecha es la que se usa para construir un selector. Un selector construido a partir de la lista amplia ofrece valores que ningún esquema de autoría acepta, y el autor se encuentra con el rechazo solo después de elegir uno.
El conjunto estrecho es también más estrecho que los tipos de entidad, y ningún esquema te dice cuáles. Un tipo propiedad de la plataforma cuyo contenido se escribe dentro del documento de otro tipo no es un documento que ofrecer a un autor para empezar. Workload es uno de esos tipos: el contenido de workload se escribe en el campo workload: de una Recipe o de una FeatureRecipe, ya sea en línea o desde un archivo que ese campo importa, así que no hay ningún documento de workload que direccionar por sí solo — consulta la superficie de autoría del Workload para saber dónde va ese contenido. Su esquema fija apiVersion y kind exactamente igual que el esquema de un tipo de autoría, porque eso es lo que permite validar el contenido donde está; los valores fijos identifican el contenido y no lo hacen direccionable. Así que no son una señal de que un tipo sea uno que bosquejar. entityKinds lleva la respuesta, y nada en los bytes del esquema la lleva.
Cada entrada de entityKinds contiene las dos grafías que necesita un cliente, y ninguna se deriva de la otra. kind es el token en minúsculas con guiones — devuélvelo como kind a este método o a aggrega/scaffoldEntity. documentKind es el valor que el propio documento lleva en su campo kind: de nivel superior. Los dos difieren en algo más que mayúsculas y minúsculas para un tipo cuyo nombre tiene más de una palabra: nada que puedas hacerle a featurerecipe llega a FeatureRecipe. Toma cada uno de la entrada en lugar de derivar uno del otro, y al cliente no le queda ninguna correspondencia que mantener.
Cada entrada dice también qué operaciones aceptan un documento de su tipo, de modo que un control que ofrece esas operaciones sobre un documento ofrece solo las que no lo rechazan por su tipo. acceptedBy contiene tres booleanos, cada uno presente en cada entrada, y cada uno trata sobre un documento del tipo nombrado por sí solo — por su ruta, o por su nombre para la inspección — sin nada más enviado junto a él. singleEntityValidation indica si aggrega validate <path> comprueba un documento del tipo, en lugar de rechazarlo y nombrar el ámbito de catálogo completo o de Release que lo comprueba en su lugar. publication indica si aggrega/publishEntity nombrando solo el documento lo publica: un Plugin es false, porque su publicación vincula además el ejecutable que una solicitud nombra en plugin, así que una solicitud que nombra solo el documento se rechaza; un Manifest y una Release son false porque ninguno de los dos tipos se publica. inspectionByName indica si aggrega/entityDefinition resuelve un nombre a una entidad del tipo, con el nombre enviado tal como se escribe donde una entidad hace referencia a otra — un Plugin como <pluginType>/<name>, y una Recipe o una FeatureRecipe como <capability>/<name>, o solo por su nombre donde una única capacidad declara ese nombre. Un true dice que la operación no rechaza el documento por ser de ese tipo; aun así puede rechazar un documento concreto por lo que dice el documento.
No mantengas una lista propia. Qué tipos existen es una propiedad del binario con el que estás hablando, así que una lista escrita en un cliente coincide el día en que se escribe y deja de coincidir el día en que se añade un tipo — y lo que el autor ve entonces es su tipo ausente del único control que debía ofrecerlo. Pregunta, y la respuesta sigue al binario.
Las dos mitades llegan juntas, y solo cuando no nombras ningún tipo. Una solicitud que nombra un tipo se responde con el esquema de ese tipo y no contiene ninguna de las dos listas, de modo que qué pregunta hiciste se lee en la respuesta. Un token al que no responde ningún esquema se rechaza con el conjunto válido completo en el mensaje, con el código invalid-params estándar, así que una errata es una solicitud que corregir en lugar de algo que preguntar a una persona.
Responde en un workspace que no contiene nada. El vocabulario está compilado en el binario, así que esto no necesita ningún documento, ningún lockfile ni ningún catálogo — que es justo el workspace en el que se encuentra un autor que empieza su primer documento.
Qué te da una respuesta de scaffold
Esta sección trata de la redacción de borradores. La otra forma del método escribe un ejemplo ejecutable, y su respuesta se describe junto con el método más arriba.
aggrega/scaffoldEntity devuelve texto. skeleton es YAML para el tipo que nombraste: cada campo que exige el esquema de ese tipo, en el orden en que el esquema los declara. Un campo que el esquema fija a un único valor llega ya rellenado —apiVersion y kind son los que notarás—, metadata.name lleva el name que enviaste, y cada otro valor obligatorio llega como un marcador de posición del tipo que el esquema declara allí: una cadena vacía, un cero, un false, una lista vacía, un mapeo vacío. kind repite el token para el que se derivó el documento, de modo que un cliente con varias solicitudes pendientes atribuye una respuesta a partir de la propia respuesta en lugar de mantener una correlación propia.
No escribe nada, y es en torno a eso que hay que diseñar. El método no crea ningún archivo, no elige ninguna ruta y no toca ningún directorio. Lo que recibes es un documento que escribir, no un documento que se ha escrito, así que un editor pone el texto en un nuevo búfer sin guardar que el autor puede leer, editar o descartar, y el momento en que un nuevo archivo llega al disco se queda donde están el búfer y el historial de deshacer. Ninguna otra solicitud toma este documento y lo coloca en algún sitio en tu nombre; decidir dónde vive un nuevo documento le corresponde al editor.
No resuelve nada y no necesita nada del espacio de trabajo. El documento se deriva de los esquemas que lleva el binario, así que el método no llega a ningún registro ni a ninguna red, no consulta ningún catálogo y no lee ningún archivo. Responde igual en cada espacio de trabajo, incluido un directorio vacío que aún no contiene ningún documento de Aggrega — que es exactamente el espacio de trabajo en el que está un autor que empieza su primer documento, y donde la mayoría de los demás métodos de aquí querrían primero un documento o un lockfile.
La misma solicitud da los mismos bytes dondequiera que se haga. El documento lo produce un único cálculo compartido con las demás superficies que ofrecen esta capacidad, de modo que un editor y un asistente a los que se pide el mismo tipo y el mismo nombre muestran al autor el mismo texto inicial.
El esqueleto lleva los campos que exige su tipo, y no es un documento terminado. Lleva los campos obligatorios y nada más: un campo opcional que quieras es uno que añades tú, y cada marcador de posición es un valor aún pendiente. Rellena los marcadores de posición y luego ejecuta aggrega/validate sobre el búfer. Para una entidad de catálogo de un tipo que aggrega validate comprueba como entidad individual, ese método nombra cada marcador de posición aún pendiente, cada uno en su clave con lo que acepta, según la misma lectura que el comando aplica al archivo guardado — incluido un marcador de posición que el esquema admite vacío; capability e implements de una Recipe o FeatureRecipe generada son los que encontrarás. Para cualquier otro tipo somete el búfer al esquema de su tipo, de modo que un marcador de posición que el esquema rechaza vacío —una versión, por ejemplo— vuelve como hallazgo de ese esquema, y uno que el esquema admite vacío no produce ninguno. Validación en vivo describe la entrada con la que llega cada marcador de posición.
Qué te dice una respuesta de importación
aggrega/import convierte una fuente escrita para otra herramienta en borradores de documentos Aggrega, y los escribe — a diferencia del scaffold anterior, que te devuelve texto. written nombra cada archivo que llegó al disco, relativo a outputDir; files lleva cada archivo que la solicitud escribe con su content, se haya escrito o no — cada borrador que produjo el importador, luego el registro de lo que escribió la importación, o con sync lo que cambia la sincronización. Los dos responden a preguntas distintas, así que lee el que corresponde a lo que preguntas: qué hay ahora en el disco, o qué se produjo.
Tú eliges dónde van los borradores, o lo dejas a la raíz del espacio de trabajo. outputDir es opcional, como lo son aggrega import --output-dir y el output_dir de la herramienta import del asistente: una solicitud que no nombra ninguno crea los borradores bajo la raíz del espacio de trabajo — donde escribe aggrega import cuando no recibe ningún destino, dondequiera que se ejecute — y una solicitud que nombra uno crea los borradores allí. Un directorio nombrado es una ruta dentro del espacio de trabajo, y un valor relativo se resuelve respecto a la raíz del espacio de trabajo y no respecto a un directorio en el que el daemon se encuentre por casualidad. La source que conviertes es el otro caso y no está confinada de este modo: ese archivo o directorio lo seleccionaste tú, así que se lee dondequiera que esté, y leerlo allí no cambia dónde quedan los borradores. El directorio se crea si no existe. Con dryRun no se escribe nada, y cada borrador sigue nombrando la ruta a la que está destinado, relativa al outputDir que nombra la respuesta — el directorio que enviaste, o la raíz del espacio de trabajo.
Una solicitud nunca sobrescribe un Aggregate que ya está en outputDir. Un Aggregate es el documento que un autor sigue editando una vez creado el borrador, así que una solicitud en la que uno de sus borradores caería sobre un archivo que se lee como un Aggregate se rechaza, nombrando el borrador y dónde está el Aggregate, y no se escribe absolutamente nada — también con dryRun, ya que una ejecución de prueba rechaza lo que la escritura rechaza. Envía en su lugar sync para actualizarlo respecto a la fuente, o nombra otro outputDir para crear el borrador junto a él. Cualquier otro archivo que ya esté en una ruta de borrador se sobrescribe, y un archivo que una importación anterior creó como borrador y que esta no crea se deja donde está. Cada solicitud que crea algún borrador también escribe .aggrega-import.json en outputDir, el registro de lo que escribió la importación — el target que se le envió, cuando se le envió uno, la instantánea del catálogo que leyó, cuando leyó una, y cada archivo de borrador y, en un Aggregate o una Release de borrador, cada clave a cualquier profundidad, con un digest del texto escrito allí, registrándose completo cualquier otro archivo de borrador — y files y written lo llevan después de los borradores. Es JSON, así que nada de lo que lee los documentos YAML del espacio de trabajo lo lee; sync, como aggrega import --sync, lo lee para actualizar los borradores respecto a su fuente. Un sync enviado sin target crea los borradores para el destino que nombra el registro, así que crea el Manifest que creó la importación anterior; uno enviado con un target crea los borradores para ese, y el registro pasa a nombrarlo. Un destino registrado al que no se vincula ninguna Recipe del catálogo se rechaza como se rechaza uno enviado, y el rechazo dice que el destino es el registrado. Como una Release de borrador se registra clave por clave, el entorno que su autor escribe donde la importación dejó un comentario para él es una clave que escribió el autor, y una sincronización la deja intacta byte a byte.
Envía sync para actualizar respecto a la fuente lo que una importación anterior creó como borrador en outputDir, cambiando solo lo que escribió la importación. Cada parte se juzga de tres maneras — lo que el registro dice que la importación escribió allí por última vez, lo que hay en el disco y lo que la fuente produce ahora. Una parte que la fuente dejó tal como la importación la escribió por última vez queda exactamente como está en el disco, la haya editado un autor o no. Una parte que la fuente cambió se escribe de nuevo, una parte que eliminó se quita — un archivo de borrador se borra entero — y una parte que ganó se añade junto a las partes que el borrador nombra a su alrededor, cada una solo donde lo que hay en el disco es lo que la importación escribió por última vez y no contiene nada que haya añadido un autor. Todo lo demás queda intacto byte a byte: una clave que un autor añadió en cualquier lugar — un parámetro, una Feature, también bajo una instancia de Component de borrador, otro Component — un comentario no escrito directamente encima de una clave de borrador, y cada archivo que el registro no enumera. Una sincronización en un directorio que no contiene ningún registro ni nada en sus rutas de borrador escribe el borrador completo, como lo hace una solicitud sin sync.
drift es lo que una sincronización actualizó, y es la respuesta a «¿ha cambiado la fuente?». Enumera cada parte que la sincronización cambió — o, con dryRun, cada parte que cambiaría — en el orden en que el borrador las nombra, cada una como change (added, removed o changed), file, el archivo de borrador en el que está, relativo a outputDir, y key, las claves que llevan a ella en un Aggregate o una Release de borrador como lista, de modo que una clave que contiene un punto sigue siendo una sola entrada; key está vacío donde la parte es el archivo completo, que es como se nombra un archivo de borrador que la sincronización borra. aggrega import imprime las mismas entradas en la salida de error estándar como <change> <key> in <file> o <change> <file>, y su código de salida con --sync --dry-run dice si la fuente se desvió; esta interfaz no tiene código de salida, así que envía sync con dryRun y comprueba si drift está vacío. drift es una lista vacía para una solicitud que no es una sincronización, para una sincronización al día con su fuente y para una sincronización cuyo importador no pudo terminar. Con sync, files lleva cada archivo de borrador que la sincronización cambia, con el contenido que le da, y después el registro cuando este también cambia, y written nombra los que llegaron al disco — así que una sincronización al día responde a ambos con listas vacías. Un archivo de borrador que la sincronización borra se nombra en drift y en ninguna de las dos listas: su entrada removed, con una key vacía, es la única mención que la respuesta hace de él, y con dryRun nombra el archivo que una escritura borraría.
Una sincronización nunca reescribe lo que escribió un autor, y en su lugar rechaza. Una sincronización que cambiaría o quitaría una parte que un autor editó, añadiría una parte donde un autor ya escribió una, o quitaría una parte que contiene algo que añadió un autor se rechaza, nombrando cada una de esas partes y el motivo en una línea propia, con las palabras que usa aggrega import --sync — <file> <key>: <why>, o <file>: <why> para un archivo completo — y no se escribe nada; un comentario escrito directamente encima de una clave de borrador edita esa clave. Una sincronización sobre un Aggregate que ningún registro enumera se rechaza nombrando el Aggregate y el registro, igual que una cuyo registro no se puede leer, ya que sin el registro sus partes no se pueden distinguir de las de un autor. Ambos rechazos vuelven como el error invalid-params, también con dryRun, y nombran sync. Concilia a mano cada parte nombrada, o restaura lo que la importación escribió allí, y envía de nuevo la solicitud.
🔴 halted: true no es un error, y tratarlo como tal es la equivocación que hay que prever en el diseño. Un importador que no pudo convertirlo todo crea igualmente los borradores de lo que pudo: la respuesta lleva esos borradores, written los nombra y diagnostics dice qué quedó fuera. Es la respuesta más útil que da la operación, y llega como resultado y no como fallo precisamente para que puedas mostrarle al autor ambas mitades. Con sync la misma respuesta no escribe nada — files, written y drift están vacíos — porque un borrador parcial se leería como una fuente que eliminó cada parte a la que el importador no llegó. Una fuente que el importador no pudo leer en absoluto es un caso distinto y sí vuelve como error.
Cada diagnóstico lleva severity y message, más code donde el importador asignó uno. Ramifica según code cuando quieras reaccionar a una condición concreta y muestra message al lector; severity se toma del mismo conjunto en el que informa cada socket de plugin — halt, warn, info — así que halted es un resumen de las entradas y no un juicio aparte. files, written, drift, diagnostics y decisions son siempre arrays, vacíos en lugar de ausentes.
decisions dice dónde adivinó la importación. Lleva una entrada por cada nodo de origen que el importador mapeó, en el orden del importador y exactamente como el importador lo informó: sourceNode, el id, el type y el paramsSummary del nodo; candidates, cada Component del catálogo que el importador sopesó para él, como componentName, score, tier y signals — lo que aportó cada una de sus señales, bajo table, category, domainLabels, shape y name; chosen, el target que eligió, el mode en el que lo escribió — una reference a un Component existente o un draft — y el tier de la elección; rationale, el porqué; y swapHint, cómo elegir de otro modo. candidates está ausente donde el importador no sopesó ninguno, chosen donde no hizo ninguna elección, y rationale y swapHint donde no escribió ninguno. Cada valor es del propio importador — cómo puntúa a un candidato y dónde caen sus niveles son decisiones suyas — así que muestra una entrada como su versión del mapeo y no como un veredicto. Las decisiones llegan tanto con dryRun como con halted a true: las conjeturas de una importación parcial son exactamente lo que necesita un autor que la revisa, y un importador que no informa ninguna responde con una lista vacía. Donde las muestres como texto, aggrega import ya formula una decisión como mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, siendo la puntuación la del mejor candidato.
El formato se reconoce a partir de la fuente, salvo que lo nombres. El reconocimiento usa las firmas que declaran los importadores — tanto los del catálogo del espacio de trabajo como los importadores básicos del compilador — y que registra la entidad Plugin de cada importador — la sintaxis en la que se lee una fuente, los nombres de archivo a los que se aplica una firma y las rutas que el árbol analizado debe o no debe contener — de modo que el propio daemon no conoce ningún formato y el formato de un importador nuevo se reconoce sin cambiar nada más. La detección lee solo la fuente que enviaste — de un directorio, solo los archivos que seleccionan los patrones de archivo de una firma — y ninguna red, analizando cada archivo que lee con el parser que el catálogo del espacio de trabajo ofrece para una sintaxis — o, para una sintaxis para la que el catálogo no ofrece ningún parser, el que incluye el propio compilador — una vez por cada sintaxis en la que lo lee una firma que se aplica a su nombre; después el importador lee la fuente con el mismo parser. Una firma que no declara ningún patrón de archivo se aplica al archivo que enviaste, se llame como se llame, y a ningún archivo de un directorio; las firmas de los importadores de Langflow, Flowise y n8n son de ese tipo y leen JSON, y la del importador de Dify lee YAML, así que reconocer un archivo enviado por sí solo lo lee como JSON y como YAML, lo cual no necesita ningún parser en el catálogo del espacio de trabajo: el compilador incluye un parser de JSON y uno de YAML, y uno que ofrezca el catálogo se usa en su lugar. Una fuente con la que no coincide ninguna firma se rechaza pidiendo format y nombrando los formatos que anuncian los importadores — o, para un directorio, pidiendo uno de sus archivos enviado por sí solo o un format cuyo importador declare patrones de archivo, nombrando solo esos — bajo la condición No importer recognises the source (Ningún importador reconoce la fuente); una fuente con la que coinciden firmas de más de un formato se rechaza nombrándolos, bajo la condición More than one importer recognises the source (Más de un importador reconoce la fuente). El data de cada rechazo lleva el code y el shortCode de su condición, de modo que un cliente pide el formato basándose en el código y no en las palabras. Ninguno de los dos se adivina, porque un formato adivinado resuelve el importador equivocado y produce disparates con aplomo. format en la respuesta es el que se usó, detectado o nombrado, de modo que un cliente que lo omitió sabe qué obtuvo.
Un directorio que envías se lee en los archivos que nombra su importador, y uno que no se puede leer es un error. Donde source nombra un directorio, el importador recibe los archivos de este que seleccionan los patrones de archivo que declaran sus firmas, excluida la carpeta de salida de compilación del espacio de trabajo dist/, cada uno nombrado por su ruta dentro del directorio, en orden, junto a los archivos que su entrada plugins.importer nombra bajo with.sources. Un importador que no declara patrones de archivo, un directorio que no contiene ningún archivo que estos seleccionen, un archivo del directorio y un archivo de with.sources con el mismo nombre, y un enlace entre los archivos que la importación leería, o hacia un directorio, que lleva fuera del directorio vuelven cada uno como un error con el código de la condición, sin que se escriba nada.
Qué importador se ejecuta lo decide el espacio de trabajo, no la solicitud. El formato se resuelve en el importador que lo anuncia entre los plugins del catálogo del espacio de trabajo y los importadores básicos del compilador — el que adjunta una entrada plugins.importer en la configuración del espacio de trabajo, donde adjunta uno de ellos — así que una solicitud no puede seleccionar un módulo ni apuntar a uno en el disco. Un formato que no anuncia ningún importador se rechaza nombrando el formato, y un formato que anuncian dos importadores sin que ninguno esté adjunto — entre ellos un importador básico y un importador de otro nombre que el catálogo contiene para el mismo formato — se rechaza como ambiguo en lugar de resolverse arbitrariamente.
Un importador básico que la máquina aún no tiene se obtiene una vez, en la primera importación que lo necesita. Procede del registro predeterminado del espacio de trabajo, ceñido al módulo que publica la versión del compilador y verificado como un pull verifica un plugin que obtiene — su firma según la política de confianza de ese registro, y las funciones de host que usa — y se guarda en la caché de contenido del espacio de trabajo, que es lo único que se escribe para él: ningún lockfile y ningún registro de plugins de confianza. Cada importación posterior lo lee de allí y no llega a ningún registro. Un módulo que no supera la verificación es un error con el código de su condición, y no se guarda nada; uno que no se puede obtener — el espacio de trabajo está sin conexión, su registro no es accesible o el registro no lo contiene — es un error bajo A plugin’s .wasm is not on this machine (El módulo de un plugin no está en esta máquina), que nombra el importador, su versión y qué pone su módulo en la máquina. La propia solicitud no nombra ningún registro, y una importación que ya tiene en la máquina todos los importadores y el catálogo que lee no llega a ninguna red.
Cuando el espacio de trabajo no nombra ninguna carpeta de catálogo, la importación lee el catálogo que publica su registro predeterminado. Un espacio de trabajo en el que ni workspace.catalog_dirs, ni AGGREGA_CATALOG_DIRS, ni la raíz nombran una carpeta de catálogo lee el catálogo de la biblioteca estándar como una única instantánea firmada, en catalog/snapshot de su registro predeterminado. Una instantánea se obtiene una sola vez: su firma se verifica según la política de confianza de ese registro, y se guarda en la caché de contenido del espacio de trabajo y se lee allí como una carpeta de catálogo, ceñida a su digest, sin volver a pedírsela a ningún registro. Qué instantánea lee una solicitud: con upgrade, la más reciente; si no, la que nombra el registro de importación en outputDir, obtenida por su digest donde la máquina no la tiene; si no, la que el espacio de trabajo obtuvo por última vez como la más reciente; si no, la más reciente. El registro que escribe la importación nombra la instantánea que leyó, por su digest, de modo que una solicitud posterior en el mismo outputDir lee el mismo catálogo. Con la postura sin conexión, una solicitud que tendría que obtener una instantánea es un error bajo The workspace is offline and the step needs the network (El espacio de trabajo está sin conexión y el paso necesita la red), que nombra qué ejecutar, y upgrade se rechaza tenga lo que tenga la máquina, ya que solo el registro puede decir qué instantánea es la más reciente. Un registro que no publica ninguna instantánea deja la importación sin catálogo, y una entrada warn en diagnostics lo indica. Un espacio de trabajo que nombra una carpeta de catálogo importa con respecto a ella y no obtiene ninguna instantánea, y upgrade no cambia nada allí.
Con dryRun no se crea nada. written está vacío, files lleva los mismos archivos que habría producido una escritura — con sync, los archivos que escribiría la sincronización, junto al drift que actualizaría — y no se crea ningún directorio — de modo que un editor puede ponerlos delante del autor para que los guarde, los modifique o los descarte. Todo lo demás que hace una escritura se hace: el mismo importador se ejecuta sobre la misma fuente e informa los mismos diagnósticos, así que una fuente que una escritura rechazaría también se rechaza aquí. Un importador básico o una instantánea del catálogo obtenidos con dryRun se guardan en la caché de contenido como con una escritura, porque adquirir aquello sobre lo que se ejecuta la importación forma parte de ejecutarla y no de colocar los borradores.
Una ruta que devuelve el importador se mantiene dentro de outputDir. Las rutas de los borradores vienen del importador y no de ti, así que una ruta que sale del directorio de salida se rechaza y no se escribe absolutamente nada — ni siquiera los borradores cuyas rutas eran correctas. El rechazo nombra la ruta problemática, y eso es lo que te indica que hay que corregir el importador y no tu solicitud.
Qué pregunta responde cada solicitud de entidad
Aquí hay cuatro solicitudes que te informan sobre una entidad, y no son intercambiables. Elegir entre ellas depende de qué tienes en la mano cuando preguntas.
Tienes en la mano un cursor. aggrega/hover y aggrega/resolve toman un archivo y una posición y deducen a qué entidad se refiere lo que está escrito allí. Cubren las formas de referencia que contiene realmente un documento — un valor de extends, un tipo de componente o de feature, el implements de una Recipe, las referencias a recipes de un Manifest, los dos punteros de ruta de una Release, un destino de uses y el propio metadata.name de una entidad. Recurre a ellas cuando el cursor del usuario es la coordenada: el usuario está leyendo un documento y quiere saber a qué apunta una referencia.
Tienes en la mano un nombre. aggrega/entityDefinition toma la identidad directamente. No hace falta tener nada abierto, no interviene ninguna posición, y la entidad no tiene que estar mencionada en ningún lugar que el cliente pueda encontrar. Recurre a ella cuando el usuario escribió un nombre, eligió uno de una lista, o siguió algo cuya identidad tu propio cliente ya conoce — un hover requiere que primero encuentres algún lugar donde esté escrito el nombre, un trabajo que no tienes por qué hacer.
Todavía no tienes nada en la mano. aggrega/catalogIndex enumera lo que contiene el espacio de trabajo, con los campos descriptivos de cada entidad. Recurre a ella para rellenar un selector y luego pasa un nombre elegido a aggrega/entityDefinition.
Tienes en la mano una Release. aggrega/releaseClosure responde sobre una Release en lugar de sobre una sola entidad, y es la sección siguiente.
La definición que devuelve una solicitud por nombre es la entidad tal como se resolvió, no como la declara un archivo concreto. Un Component o una Feature que extiende una base vuelve con el contrato de esa base, que no aparece en ninguna parte del documento que declara su nombre — así que la respuesta trata de lo que la entidad es, y leer tú mismo el archivo no te daría lo mismo.
Llega como un documento YAML y no como una estructura dentro de la respuesta, y es deliberado: un pilar de esquema tiene varias formas de redacción — contenido escrito por completo, una referencia a un documento compartido, o el marcador que indica que el contenido viene de una base — y el documento reproduce aquella a la que llegó la resolución, en el orden de claves del propio autor. Analízalo como documento si necesitas sus campos; muéstralo tal cual si lo vas a poner en un panel.
Distinguir los dos rechazos por nombre
Un nombre que no se resuelve en nada se rechaza en lugar de responderse con un documento vacío, porque una respuesta vacía presentaría una errata como una entidad sin nada que decir de sí misma. Hay dos formas en que un nombre no se resuelve en nada, piden cosas distintas al lector, y las distingues por lo que lleva el data del error, no leyendo el mensaje:
- Ningún
fileendata. Nada en el espacio de trabajo declara ese nombre y ningún nivel del catálogo lo resuelve. Casi siempre es la solicitud la que hay que corregir — una errata, o un nombre de un catálogo que este espacio de trabajo no tiene en su ruta de búsqueda. - Un
fileendata. Un documento del espacio de trabajo sí declara ese nombre, y aun así el catálogo no resolvió nada para él. La entidad está escrita y algo la rechazó, lo cual es un estado del espacio de trabajo que repara una persona. Donde exactamente un documento que el catálogo leyó y rechazó declara ese nombre — la causa habitual — el mensaje empieza por ese rechazo, expresado una sola vez: su categoría y su código corto, el documento por la ruta con la que se informa, y qué está mal en él, como la línea y la restricción que infringe; luego indica que el archivo se omitió en la carga y enumera cualquier otro archivo que la carga rechazó. En caso contrario, el mensaje nombra el documento que lo declara, enumera los archivos que rechazó la carga y dice de dónde lee este espacio de trabajo las entidades locales y qué cambiar para que se lea el documento — la explicación que omite cuando un documento rechazado declara el nombre, porque ese documento ya está donde lee el catálogo.
Ambos llevan el código entity-not-resolvable, así que ramifica según la presencia de file y no según el código.
Preguntar por una coordenada
Tienes en la mano una referencia de registro. Envíala como name de aggrega/entityDefinition, y la respuesta es la entidad publicada en esa coordenada, con la misma forma de resultado que obtiene un nombre más published, rellenada a partir de lo que se publicó y no de lo que resolvió un catálogo:
definitiones el documento de la entidad exactamente como se publicó. Una coordenada cuya entidad se publicó con los archivos que declara lleva un archivo comprimido, y el documento se extrae de él; una cuya entidad no declara ningún archivo lleva su documento sin cambios, y la entidad de un Plugin se lee de su manifiesto y no del ejecutable publicado con él. No se aplica ninguna herencia.authoredLengthes la longitud de ese documento, porque aquí la definición es un documento redactado y no la representación de uno resuelto.fileestá vacío, porque una entidad leída de un registro no tiene en esta máquina ningún documento que nombrar.publishScopese omite: ya tienes en la mano la coordenada, que es donde está publicada la entidad.publishedes lo que se leyó, y está presente en esta respuesta y en ninguna por nombre: lareference;archive, si sus bytes eran un archivo comprimido del que se extrajo el documento —falsedonde la coordenada contenía el propio documento; elmediaTypeque declara el manifiesto; y elmanifestDigestde ese manifiesto, que puedes enviar después de@en lugar de la etiqueta para volver a leer exactamente los mismos bytes.
La solicitud llega al registro que nombra la referencia, con las credenciales del usuario con el que se ejecuta este daemon y la configuración de red de este espacio de trabajo, así que un espacio de trabajo sin conexión la rechaza. Los bytes obtenidos se comprueban contra el digest que el propio manifiesto del artefacto registra para ellos y contra nada más — no se verifica ninguna firma ni se informa de ninguna retirada — y no se escribe nada. Una referencia que no se puede leer se rechaza con entity-not-resolvable, y el mensaje empieza con el código corto de la condición que dice por qué — las mismas condiciones que informa aggrega inspect — y termina con qué hacer al respecto. Una referencia que no nombra ningún repositorio, o ni una etiqueta ni un digest, es una solicitud mal formada y se rechaza como parámetros no válidos.
Un cierre no es el grafo
aggrega/irGraph y aggrega/releaseClosure se derivan de la misma resolución de la misma Release y responden a preguntas distintas. Un cliente que ya recibe el grafo puede suponer razonablemente que también tiene esta, y no es así.
El grafo dice qué despliega la Release — sus nodos, los límites en los que se encuentran, qué está conectado con qué, y los valores y adjuntos que lleva cada nodo. Es la imagen.
El cierre dice qué se incorporó para construirla, y en qué versiones. Cada entidad a la que llega la Release, se haya convertido en nodo o no; los documentos compartidos de los que se sirven esas entidades; y los plugins que dan forma a la salida. Es la lista de materiales.
Ninguno se puede recuperar a partir del otro. Se puede llegar a una entidad sin que llegue a aparecer nunca como nodo — la Recipe a la que un Manifest mapea un tipo de componente es alcanzada por cada compilación y no es un nodo en ninguna de ellas — y un nodo no lleva la versión en la que se resolvió su tipo. Así, un lector que pregunta «¿por qué cambió esta versión?», «¿a qué afectaría cambiar este documento compartido?» o «¿de qué depende realmente esta Release?» está pidiendo el cierre, y un lector que pregunta «¿qué despliega esta Release?» está pidiendo el grafo.
Lo que no hace la solicitud de cierre. No renderiza nada y no publica nada de lo que encuentra. En particular, no emite ninguna advertencia de deriva ni ningún aviso de renderizado: esos pertenecen a la solicitud que los pidió, y publicar reemplaza una capa entera de diagnósticos, así que un listado que publicara borraría lo que la solicitud del grafo ya había puesto delante del usuario. Pide el grafo cuando quieras el veredicto de deriva. Lo único que sí publica no es un hallazgo propio: una solicitud que encuentra que el lockfile ha desaparecido retira la advertencia de deriva que se apoyaba en él, sea cual sea la solicitud — consulta Conciencia del lockfile.
Requiere un lockfile, igual que el grafo. Las versiones que informa el listado son aquellas en las que se resolvió esta Release, y un espacio de trabajo que nadie ha preparado aún no las ha resuelto. Un listado producido sin lockfile informaría de lo que el catálogo contiene por casualidad hoy, que es una pregunta distinta de aquello de lo que depende esta Release. El rechazo nombra el lockfile y la Release, de modo que un cliente puede ofrecer directamente aggrega pull --release <release>.
kind en una entrada del cierre está presente solo donde se conoce. Una referencia se recoge desde una posición en un documento, y algunas posiciones dicen a qué tipo de entidad apuntan mientras que otras no. El campo se informa donde el lugar de la referencia registró uno y se omite donde no, en vez de adivinarse a partir de la forma del nombre. Se informa como la palabra que un autor escribe en la cabecera de un documento, que es la misma palabra que usa para la misma entrada cada interfaz que informa de un cierre.
La misma palabra pide el mismo documento en otros lugares. aggrega inspect <release> --closure responde a esta pregunta en la línea de comandos, y el modo release de la herramienta describe la responde mediante el protocolo de herramientas del asistente. Los tres ejecutan una única resolución sobre la Release, así que no pueden llegar a discrepar sobre aquello de lo que depende una Release. Consulta aggrega inspect, «El cierre de dependencias».
Modelo de caché
Las operaciones se basan en la caché: llama a aggrega/validate para un archivo antes de hover / completion / resolve / diagnostics sobre él. Esa llamada de inicialización no necesita una Release — una validación que no nombra ninguna analiza igualmente el búfer y llena la caché — así que estas operaciones funcionan en un espacio de trabajo que no tiene ninguna Release que nombrar. La caché de análisis se contrasta con la fecha de modificación en disco de cada archivo en cada lectura, de modo que los cambios externos (un guardado del editor, un git checkout) se detectan automáticamente — el aggrega/invalidate del editor es una optimización, no un requisito de corrección.
La caché pertenece al espacio de trabajo que la inicializó. Un archivo validado en un espacio de trabajo se guarda en caché para ese espacio de trabajo, así que la misma ruta consultada en otro se informa como aún no validada en lugar de responderse a partir de la entrada del primero. Eso es lo que evita que una pregunta sobre un segundo espacio de trabajo responda erróneamente o le cueste al primero su estado ya caliente — y aggrega/invalidate igualmente solo vacía el espacio de trabajo que nombra.
Pedir diagnósticos mientras se ejecuta una validación
Una validación inicializa dos cosas sobre un archivo — el análisis que entrega a las demás operaciones y los hallazgos que informa — y las inicializa con un instante de diferencia. aggrega/diagnostics es la única solicitud que lee ambas: necesita el análisis para saber que el archivo es uno sobre el que puede responder, y responde a partir de los hallazgos. Así que una solicitud que llegara entre esos dos instantes estaría decidiendo que puede responder cuando todavía no hay nada con qué responder.
En su lugar, espera. Envía aggrega/diagnostics para un archivo que se está validando en este momento y la respuesta llega cuando esa validación termina, con lo que encontró. Hay una única respuesta correcta para el archivo sea cual sea el momento, y esa es la respuesta que obtienes — nunca es una lista vacía para un archivo cuya validación está a punto de informar errores, que es la única respuesta errónea de la que un cliente no puede recuperarse, porque nada te lleva a volver a preguntar por un archivo del que se te dijo que estaba limpio. Las demás operaciones basadas en la posición — hover, completion, resolve, findReferences, findImplementations — leen el análisis y responden a partir del análisis, así que no tienen nada que esperar y nunca esperan.
Dos cosas terminan la espera antes de tiempo, y ambas ya las tienes. $/cancelRequest para el id de esa solicitud la detiene, y un aggrega/shutdown cooperativo la detiene. Ninguna de las dos necesita nada adicional en la solicitud.
Y la espera tiene un límite. Si la validación no ha terminado dentro del margen que el daemon le concede, la solicitud se rechaza con el código validation-in-flight en lugar de responderse vacía — consulta Códigos de error. Ese rechazo significa que el trabajo que esperas está realmente en curso, así que lo que hay que hacer es volver a preguntar en breve; no es una señal para enviar otra validación, que añadiría trabajo y no respondería nada.
Un daemon que ejecuta las solicitudes de una en una las responde en orden de llegada, así que nada se solapa y nunca hay espera. Un daemon que las ejecuta de forma concurrente responde a las mismas preguntas de la misma manera, y la espera es lo que lo hace cierto: la respuesta que obtienes es la que te habría dado un orden en serie.
Tamaños en una respuesta
Una respuesta que informa una cantidad de bytes la informa dos veces: como el número y como la misma cantidad escrita. El campo escrito es el nombre del campo numérico con Text añadido al final — size y sizeText, totalSize y totalSizeText, reclaimedBytes y reclaimedBytesText, y así en cada respuesta que lleva un tamaño.
Muestra la forma escrita y calcula con el número. El sentido de enviar ambos es que un cliente nunca tenga que formular un tamaño por su cuenta: el daemon lo escribe con el mismo formateador que usa la línea de comandos, así que aggrega cache status y aggrega/cacheStatus muestran una caché dada de forma idéntica, hasta el redondeo. Un cliente que compusiera su propio texto se apartaría de eso la primera vez que discrepara sobre un umbral.
La forma escrita usa unidades binarias — 512 B, 1.0 KiB, 5.0 MiB, 3.0 GiB — que es el mismo vocabulario que aggrega/cacheEvict acepta en maxSize, así que un tamaño leído de una respuesta se puede enviar de vuelta en la siguiente solicitud sin reescribirlo. Por encima de los bytes, el texto lleva un decimal, de modo que expresa la cantidad como un lector quiere verla y no al byte; cuando necesites el recuento exacto, para eso está el campo numérico.
Donde el número es opcional, el texto es opcional con él, y los dos nunca están presentes a medias: el tamaño del plugin en una respuesta de publicación lleva pluginSize y pluginSizeText juntos o no lleva ninguno.
Cada solicitud nombra el espacio de trabajo al que se refiere
Envía workspaceRoot en cada solicitud: la ruta absoluta de la raíz del espacio de trabajo sobre el que actúa esa solicitud. El daemon no tiene ningún espacio de trabajo propio y no recuerda ninguno entre solicitudes, así que aquello sobre lo que se responde a una solicitud es el espacio de trabajo que nombró y nada más. Dos solicitudes que nombran dos espacios de trabajo obtienen dos respuestas, y ninguna puede ver las entidades, Releases, análisis en caché o diagnósticos de la otra.
Una solicitud que no nombra ninguno se rechaza con el error invalid-params estándar que nombra el parámetro, y lo mismo un valor vacío, que no indica ningún espacio de trabajo y se responde como uno ausente. Otras dos formas se rechazan por el mismo motivo, cada una nombrada en el mensaje: una ruta relativa, porque una raíz de espacio de trabajo no tiene nada respecto a lo que ser relativa; y una ruta que no es un directorio existente, porque un espacio de trabajo es un árbol.
Tres solicitudes no necesitan workspaceRoot, y cada una porque su objeto no es un espacio de trabajo. aggrega/getSchema y aggrega/scaffoldEntity responden a partir de los esquemas compilados en el binario en ejecución, así que un espacio de trabajo no aporta nada a ninguna de las dos — que es lo que permite a ambas responder en un directorio que nadie ha preparado. aggrega/initialize es la tercera, y es donde declaras un espacio de trabajo en lugar de actuar sobre uno. La otra forma de aggrega/scaffoldEntity, que escribe o lista los ejemplos ejecutables de la documentación, sí actúa sobre un espacio de trabajo, y una solicitud para ella nombra uno como cualquier otra.
El estado en caché de cada espacio de trabajo se guarda por separado, y nombrar un segundo no le cuesta nada al primero. El índice del catálogo, la caché de análisis y los diagnósticos de un espacio de trabajo pertenecen a ese espacio de trabajo, así que una pregunta hecha sobre otro lugar no desaloja lo que un editor ha ido acumulando para la carpeta que alguien tiene abierta. Dos grafías de una misma raíz son un único espacio de trabajo, así que una ruta que lleva un . interior o un separador duplicado llega al mismo estado caliente que su forma simple.
Declarar el espacio de trabajo para el que quieres recibir diagnósticos por push
Los diagnósticos viajan de dos maneras: los pides tú, o el daemon te los envía por push. El daemon envía por push solo para el espacio de trabajo que declaraste en el handshake. Cualquier otra solicitud responde con sus hallazgos en su propia respuesta y no envía nada por push.
Decláralo enviando workspaceRoot en aggrega/initialize. Eso es todo lo que hace la declaración — no ancla nada, y ninguna solicitud posterior se responde en función de ella.
El motivo para restringirlo es para qué sirve un diagnóstico enviado por push. El push es lo que mantiene al día la lista de problemas de un editor mientras alguien escribe, y es exactamente lo que no hay que hacer con una respuesta que nadie pidió ver: sin la regla, una pregunta hecha sobre un segundo espacio de trabajo — por otra herramienta que comparte el daemon, por ejemplo — llenaría la lista de problemas de un lector con hallazgos sobre archivos que nunca abrió. Restringir el push mantiene la pregunta de un llamador fuera de la lista de problemas de otro llamador.
El campo es opcional, y las tres cosas que puedes querer decir con él se pueden distinguir:
| lo que envías | adónde van los push | lo que informa el handshake |
|---|---|---|
| nada | el espacio de trabajo sobre el que se lanzó el proceso | ese espacio de trabajo |
| una raíz de espacio de trabajo | ese espacio de trabajo | ese espacio de trabajo |
| la cadena vacía | a ninguna parte — nunca se envía ningún diagnóstico por push | una raíz vacía |
No enviar nada deja los push en el espacio de trabajo sobre el que se lanzó el proceso, así que un cliente que no declara nada recibe los diagnósticos de ese espacio de trabajo. Enviar la cadena vacía es la declaración honesta para un llamador que no es un editor y no tiene ninguna lista de problemas que mantener sincronizada: cada hallazgo le sigue llegando, en la respuesta a la solicitud que lo produjo.
Un espacio de trabajo declarado se resuelve exactamente igual que uno nombrado en una solicitud, así que una declaración que nombra una ruta relativa, o una ruta que no es un directorio, se rechaza en el handshake en lugar de dejar los push dirigidos a algún lugar inesperado.
Raíz del espacio de trabajo y Release activa
El daemon resuelve cada espacio de trabajo que nombra una solicitud del mismo modo en que lo resuelve cada comando aggrega, y Configuración recoge qué ancla una raíz y en qué orden. Dos consecuencias importan a un cliente. Un .aggrega-config.yaml sin un bloque workspace: no ancla: sigue aportando sus ajustes, pero un simple archivo de ajustes no puede convertir cada directorio superior en una raíz de espacio de trabajo. Y cuando nada ancla, se usa el directorio de trabajo — el daemon arranca y las operaciones simplemente no resuelven nada, en lugar de negarse a ejecutarse.
El proceso también se lanza sobre un espacio de trabajo, a partir de --workspace-root o subiendo desde su directorio de trabajo, y esa resolución hace dos cosas y ninguna otra: dimensiona el pool de workers, que es una propiedad del proceso y no de una solicitud, y es la declaración predeterminada para los diagnósticos enviados por el daemon. Ninguna solicitud se responde con respecto a ella.
La configuración es igualmente la misma cascada que lee cada comando, y Configuración es donde se describe. Lo único que añade el daemon es que la lectura que hace cada espacio de trabajo se realiza una vez, cuando ese espacio de trabajo se nombra por primera vez, y se reutiliza para cada solicitud posterior sobre él. Un archivo de configuración que esa cascada leería y que es un enlace que lleva fuera del espacio de trabajo — el propio .aggrega-config.yaml del espacio de trabajo, o la capa superpuesta propiedad de la CI junto a él — no se lee, aquí igual que en una terminal, y nada más de lo que ese archivo habría configurado se lee en su lugar. Lo que difiere de una terminal es lo que sigue respondiendo. El daemon lanzado sobre un espacio de trabajo así arranca, y lo indica una vez en su flujo de errores; una solicitud que nombra uno se responde como sigue en cualquier caso. aggrega/releaseCandidates y aggrega/catalogIndex — las dos solicitudes que listan lo que contiene un espacio de trabajo — la responden, leyéndolo sin nada configurado: se listan los documentos propios del espacio de trabajo, no se lee ningún directorio de catálogo y el archivo retenido se nombra en unreadLinkedFiles, tanto si la búsqueda lo encontró como si no. Ese nombre es la forma en que un cliente sabe que la configuración del espacio de trabajo lleva fuera de él. Cualquier otra solicitud que nombre el espacio de trabajo — un build, un grafo, una validación, la Release predeterminada, la configuración efectiva, una escritura y aggrega/catalogIndex en términos de una Release — depende de esa configuración, por lo que se rechaza con el error invalid-params que lleva E0321 — read-leads-out-of-workspace en el data del error — y la frase que nombra el enlace y adónde lleva. El handshake también responde para un espacio de trabajo así, indicando defaults como su configSource, ya que ningún archivo de configuración aportó nada de aquello con lo que responden los listados. Elimina el enlace, o haz que lleve a un archivo dentro del espacio de trabajo, y la siguiente solicitud lee la configuración. Bajo los archivos del proyecto está la capa global: el archivo que --config nombra en la línea de comandos que inició el daemon, para cada espacio de trabajo al que sirve; si no, el archivo que nombra la variable de entorno AGGREGA_CONFIG cuando está definida; y si no, la ubicación predeterminada — en Windows aggrega\config.yaml dentro del directorio que nombra la variable de entorno APPDATA, y en otros sistemas aggrega/config.yaml dentro del directorio que nombra XDG_CONFIG_HOME, con ~/.config/aggrega/config.yaml como alternativa — que se carga cuando está presente. Debajo de ella están los valores predeterminados integrados.
Las operaciones que actúan sobre una Release reciben una como parámetro; el daemon no selecciona ninguna por su cuenta. Un espacio de trabajo sigue declarando a qué Release apunta, y una cascada de cuatro pasos lee esa declaración: el campo de configuración build.authoring_release, luego un archivo marcador .aggrega/active-release, luego una heurística de una única Release en el espacio de trabajo, luego un recurso de último caso basado solo en el Aggregate. Por tanto, un marcador que escribes tiene prioridad sobre la heurística, y un marcador que nombra una Release que no se puede cargar pasa a la heurística en lugar de al recurso de último caso. Un marcador que nombra una Release fuera del espacio de trabajo — mediante una ruta absoluta, una ruta que sale por encima de la raíz o un enlace que lleva fuera de ella — no se lee, salvo que la configuración de tu espacio de trabajo nombre esa Release como build.authoring_release o como clave de workspace.releases: la configuración es la forma de llegar a una Release guardada fuera del espacio de trabajo, y el marcador no lo es. La cascada continúa entonces exactamente como lo hace con un marcador que no puede cargar, y donde no llega a nada, trace indica por qué en la línea del marcador y reason en su frase sobre el marcador.
aggrega/activeRelease informa de lo que elige esa cascada, y es una sugerencia para un cliente más que un ajuste según el cual actúe el daemon. Pregunta al daemon en lugar de leer tú mismo las entradas de la cascada: el campo de configuración y el archivo marcador son dos de cuatro entradas, así que cualquiera de ellas que leas nombra la elección del espacio de trabajo solo cuando resulta ser la entrada que ganó. Un marcador que nombra una Release que no se puede cargar es el caso más claro — la cascada elige una Release totalmente distinta, y quien leyera el marcador informaría de la que falló.
La cascada se ejecuta cuando lo pides y no antes, lo que tiene dos consecuencias en las que conviene confiar. El handshake sigue siendo rápido sea cual sea el tamaño del árbol, porque no espera al recorrido del espacio de trabajo. Y la respuesta sigue al espacio de trabajo: escribe un marcador — con aggrega/setActiveRelease, que responde con la propia nueva elección — edita la configuración, añade o elimina un archivo de Release, vuelve a preguntar y obtendrás la nueva respuesta del mismo daemon. Cambiar la Release en la que trabajas nunca requiere reiniciar el daemon — un cliente envía un release distinto en su siguiente solicitud.
Las operaciones que buscan en todo el espacio de trabajo en lugar de en un solo búfer — completion, hover, resolve, findReferences y findImplementations — enumeran el YAML bajo la raíz del espacio de trabajo, y esa enumeración respeta .gitignore. Cada .gitignore desde la raíz del espacio de trabajo hasta el propio directorio del archivo contribuye, y prevalece el más cercano, de modo que un archivo YAML que tu repositorio ignora no se ofrece como candidato de autocompletado ni se informa como definición o referencia. Un .gitignore que es un enlace que lleva fuera del espacio de trabajo no se lee, de modo que un archivo situado en otro lugar de la máquina nunca decide en qué documentos del espacio de trabajo se busca. Los árboles de dependencias incluidas y la salida generada quedan así fuera de los resultados entre archivos sin ningún ajuste de exclusión aparte que mantener — y un documento que esperas que se encuentre pero que has ignorado no aparecerá, que es el único caso que conviene comprobar cuando parece faltar una referencia. Los Components y las Features que completion también ofrece desde tus catalog_dirs configurados son una lectura distinta: proceden de esos directorios tal como están configurados — los mismos directorios que lee un build de una Release cuando la configuración no le asigna ninguno propio, o, para una solicitud que nombra una Release, los de esa Release — de modo que las entidades de un directorio de catálogo se ofrecen tanto si un .gitignore lo cubre como si no — salvo una entidad situada tras un enlace que lleva fuera del directorio dentro del cual deben quedarse las lecturas de un directorio de catálogo, que no se lee ni se ofrece.
Una solicitud que nombra una Release lee los directorios de catálogo de esa Release, que son los que lee un build de ella en una terminal: los suyos propios, donde la configuración del espacio de trabajo le asigna algunos bajo workspace.releases, y en otro caso los catalog_dirs del espacio de trabajo. Eso abarca aggrega/build, aggrega/buildPreview, aggrega/irGraph, aggrega/releaseClosure, aggrega/resolveDependencies, aggrega/validate y aggrega/lint cuando nombran una Release, aggrega/attachCandidates y aggrega/attachmentContainer dirigidas a un nodo del grafo de una Release, y aggrega/connectionAtPosition, además de las solicitudes que enumera la sección siguiente cuando nombran una. Así, una sola sesión responde por cada Release de un espacio de trabajo que mantiene una variante de catálogo por Release, cada una a partir de su propia variante, sin enviar nada más que la ruta de la Release. Una solicitud que no concierne a ninguna Release concreta — aggrega/catalogIndex, aggrega/entityDefinition, completion, hover y resolve sin nombrar ninguna Release, y aggrega/attachCandidates dirigida a una entidad o a un conjunto de etiquetas — lee los catalog_dirs del espacio de trabajo. aggrega/lint sin nombrar ni una entidad ni una Release es la excepción en un espacio de trabajo que nombra Releases bajo workspace.releases: allí comprueba el catálogo completo una vez por cada Release, cada pasada sobre los directorios de esa Release, como describe Publicar convenciones, a petición y en cada edición. Consulta Dar a una Release sus propios directorios de catálogo.
Responder en términos de una Release
aggrega/catalogIndex, aggrega/entityDefinition y las cinco solicitudes que parten de un cursor — aggrega/hover, aggrega/resolve, aggrega/completion, aggrega/findReferences y aggrega/findImplementations — no conciernen a ninguna Release concreta, y cada una acepta un release opcional que hace que concierna a una. Es una ruta relativa a la raíz del espacio de trabajo, sujeta al mismo contrato que le aplican las demás solicitudes que aceptan una Release; un valor que no nombra ningún archivo de Release, o que nombra un directorio, se rechaza en lugar de responderse en términos del espacio de trabajo mientras se lee como la respuesta de la Release.
Lo que una Release alcanza, para cada solicitud de aquí: los documentos del espacio de trabajo bajo los directorios de catálogo que lee su pila, y cada documento del espacio de trabajo que no está bajo ningún directorio de catálogo — una Release, su Aggregate y su Manifest escritos junto a los catálogos. Un documento del espacio de trabajo bajo un directorio de catálogo que solo leen otras Releases no forma parte de su respuesta: ni se lista, ni se resuelve, ni se ofrece. Eso es lo que evita que se confundan variantes de una misma entidad, mantenidas una junto a otra para Releases distintas.
- El listado. Nombrar una Release lista las entidades que esa Release ve. Las Features listadas son las que declaran los directorios de catálogo de esa Release, y un documento del espacio de trabajo bajo un directorio de catálogo que solo leen otras Releases queda fuera — de modo que un espacio de trabajo que mantiene una variante de una entidad por Release lista la única variante con la que se construye esa Release, en lugar de todas las variantes una junto a otra. Un documento que no está bajo ningún directorio de catálogo, como una Release, su Aggregate y su Manifest escritos junto a los catálogos, pertenece al listado de cada Release.
- Una búsqueda por nombre. Al nombrar una Release, el nombre se resuelve a través de los directorios de catálogo de esa Release, de modo que un nombre que declaran varias variantes se resuelve en la variante con la que se construye esa Release. Un nombre que sus directorios no resuelven se rechaza con una explicación que nombra la entrada de esa Release bajo
workspace.releases, ya que esa entrada es lo que leyó la búsqueda. Una referencia de registro no acepta ninguna Release, y se rechaza si recibe una: se lee del registro que la publica, sea cual sea la Release nombrada. - Hover e ir a la definición. Al nombrar una Release, la referencia bajo el cursor se resuelve primero a través de los directorios de catálogo de esa Release, en el orden que les da la configuración del espacio de trabajo — la misma resolución que realiza una búsqueda por nombre en términos de esa Release — de modo que la entidad mostrada, y el documento abierto, es la variante en la que esos directorios la resuelven, incluso donde un documento del espacio de trabajo en otro lugar declara el mismo nombre. Solo donde ningún documento bajo esos directorios responde por ella se busca en los documentos del espacio de trabajo que esa Release alcanza. Sin nombrar ninguna, el orden es el inverso: se busca primero en los documentos del espacio de trabajo, de modo que una referencia a la que responde un documento del espacio de trabajo conserva esa respuesta, y los
catalog_dirspropios del espacio de trabajo se consultan solo donde ningún documento declara el nombre — que es lo que encuentra una entidad que solo contiene un directorio de catálogo configurado, incluido uno fuera del árbol del espacio de trabajo. Donde el editor tiene una copia sin guardar del documento en el que se resuelven los directorios de una Release, y esa copia sigue declarando el nombre, la respuesta se lee de la copia, de modo que una posición cae en la línea que muestra el editor. - Autocompletado. Al nombrar una Release, los nombres ofrecidos son los que declaran los documentos del espacio de trabajo que esa Release alcanza, junto con los Components y las Features que declaran los directorios de catálogo de esa Release.
- Referencias e implementaciones. Al nombrar una Release, una ubicación en un documento del espacio de trabajo que esa Release no alcanza no se informa, de modo que una variante mantenida para otra Release nunca se lista como referencia o implementación de esta.
- Qué puede adjuntarse a un nodo del grafo.
aggrega/attachCandidatesdirigida a un nodo del grafo de una Release está siempre en términos de esa Release — consulta Qué te dice una respuesta de candidatos a adjuntar.
Sin nombrar ninguna, se responde sobre los directorios de catálogo propios del espacio de trabajo, como describe el párrafo anterior.
Llegar a un registro, y escribir
La mayoría de las solicitudes de aquí responden a partir del espacio de trabajo y de lo que ya está en caché, y no escriben nada. Unas pocas, nombradas, hacen más, y se dividen según dos ejes independientes: lo que una solicitud alcanza, y hasta dónde llega lo que cambia.
Las solicitudes que salen a un registro se dividen en las que leen y las que publican. aggrega/resolveDependencies obtiene lo que necesita una Release, y aggrega/build se le une cuando — y solo cuando — su campo autoPull le pide resolver primero las dependencias, en cuyo caso alcanza un registro y escribe el lockfile antes de renderizar; aggrega/registryUpdate recorre cada registro configurado para reconstruir el índice de búsqueda local; aggrega/pluginAdd busca en el registro configurado el plugin que nombra una solicitud y lee sus versiones publicadas para fijar una; aggrega/registryAdd pide al registro que registra la política de confianza que ese registro anuncia, salvo que la solicitud renuncie a obtenerla o aporte una política propia, y aggrega/configInit pide lo mismo al registro que está inicializando; aggrega/explainError adquiere el paquete de documentación del que lee la explicación detallada de una condición, una sola vez, donde la caché que comparten todos los proyectos de la máquina no contiene ninguna copia que admita la comprobación de firma propia del espacio de trabajo — consulta aggrega explain; aggrega/scaffoldEntity enviado con example o list adquiere el mismo paquete en las mismas condiciones, y una escritura escribe después el ejemplo en un directorio nuevo del espacio de trabajo; aggrega/import obtiene un importer básico del registro predeterminado del espacio de trabajo, una sola vez, donde la máquina aún no lo tiene, y, en un espacio de trabajo que no nombra ninguna carpeta de catálogo, la instantánea publicada del catálogo que lee — consulta Qué te dice una respuesta de importación; y aggrega/entityDefinition lee la entidad que nombra una referencia de registro cuando se envía una como su name, sin escribir nada. aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts y aggrega/deprecateArtifact escriben en uno — bytes, una firma o un marcador de retirada. Una solicitud alcanza un registro solo cuando se envió para hacerlo: un listado informa de lo que fija la configuración, una búsqueda lee una instantánea sin conexión y una publicación pedida con dryRun calcula lo que enviaría y no contacta con nadie.
La regla trata de cuándo se ejecuta una operación, no de qué superficie la ejecuta. Una operación que obtiene o escribe se ejecuta porque una solicitud la nombró, y nunca como efecto secundario de validar un documento, inspeccionar un grafo o listar las entidades de un espacio de trabajo. Así, un editor que valida en cada pulsación no alcanza ninguna red ni reescribe ningún lockfile, mientras que una acción «resolver dependencias» en la que el usuario hace clic hace exactamente lo que hace aggrega pull — la misma resolución, tras ambas superficies, que escribe un lockfile idéntico byte a byte y llena la misma caché de artefactos.
No se pide nada. Nadie está observando este flujo, así que la identidad se resuelve a partir de una fuente de credenciales proporcionada o presente en el entorno, y nunca preguntando. Donde el comando de terminal habría hecho una pregunta a una persona — un registro que necesita credenciales, una capacidad que sirve más de un plugin de provider, el texto que debe llevar una retirada — la solicitud falla con un mensaje que nombra qué proporcionar en lugar de quedarse bloqueada esperando una respuesta que nunca llegará. Un rechazo deja el espacio de trabajo exactamente como estaba: no se escribe ningún lockfile ni se deja ningún registro parcial, y una publicación que no pudo resolver una credencial se rechaza antes de que ningún byte llegue al registro.
Algunos cambios van más allá de este espacio de trabajo, y la respuesta dice cuáles
Una solicitud nombra un espacio de trabajo, así que una respuesta que no dice nada sobre su propio alcance se lee como referida a ese espacio de trabajo. Para varias de estas solicitudes esa lectura sería errónea, así que cada una lleva su alcance y un cliente debería mostrarlo antes de actuar sobre el resultado.
Publicar, firmar y retirar van totalmente más allá de la máquina, que es el mayor alcance de cualquier cosa de aquí. Las demás escrituras de abajo cambian lo que resuelve esta máquina; estas cambian lo que hace cualquiera que resuelva desde ese registro. Los bytes publicados son lo que obtiene cada consumidor de ese registro, y volver a publicar contenido distinto sobre una etiqueta se rechaza en lugar de ofrecerse, así que ninguna solicitud de aquí deshace una publicación — la respuesta es publicar una nueva versión. Una firma y un marcador de retirada se adjuntan junto al artefacto en lugar de sustituirlo, de modo que los propios bytes quedan intactos; pero cualquiera que obtenga el artefacto después los obtiene también, y ninguno de los dos puede recuperarse de quien ya lo tiene. Una retirada es la más fácil de malinterpretar de las tres: la versión sigue pudiéndose obtener, mientras que una retractación en la que confía un espacio de trabajo la saca de lo que elegirá allí una resolución.
La firma usa credenciales, y conviene saber de dónde vienen antes de conectar un cliente. La firma sin clave resuelve un token de identidad, en orden, a partir de identityToken en la solicitud, luego de AGGREGA_IDENTITY_TOKEN en el entorno del daemon, luego del endpoint OIDC de GitHub Actions presente en el entorno donde haya uno accesible, luego de SIGSTORE_ID_TOKEN. Cuando ninguno de ellos proporciona un token, la operación se rechaza y nombra qué enviar; nunca abre un navegador, porque no hay nadie para mirarlo. La firma con clave es la alternativa sin conexión, y una solicitud no nombra ninguna ruta de clave: lo que lee una solicitud se encuentra dentro del espacio de trabajo que nombró, y una clave privada nunca se guarda dentro de un espacio de trabajo, así que la clave procede en cambio del bloque signing: de la configuración propia de ese espacio de trabajo. Consulta aggrega sign para los dos modos de firma y con qué contacta cada uno.
Cada una de las cuatro respuestas lleva reach, que contiene registries — cada host de registro al que se dirigió la llamada, cada uno nombrado una vez, en el orden en que la llamada se dirigió a él por primera vez, de modo que un lote de firma o un archivo de lote cuyas referencias abarcan varios registros los nombra a todos — y beyondThisMachine, que se deriva de lo que la llamada adjuntó realmente y no de lo que pidió: verdadero exactamente cuando subió contenido o adjuntó una firma, una fecha de publicación o un marcador de obsolescencia, y falso para una ejecución de prueba y para una llamada que encontró ya presente todo lo que habría adjuntado — una publicación ejecutada de nuevo sobre una versión que ya está completa, o un lote de firma en el que cada referencia ya llevaba una firma que se verifica. Una ejecución de prueba sigue nombrando el destino al que se habría dirigido. Muéstralo antes de actuar sobre el resultado.
Registrar o eliminar un registro escribe la configuración compartida por todos los espacios de trabajo de la máquina, de forma predeterminada. Un registro y las identidades en las que confías en él suelen ser los mismos dondequiera que trabajes, así que ahí va la entrada salvo que la solicitud envíe workspace: true. Conviene decir claramente la consecuencia: aggrega/registryAdd y aggrega/registryRemove cambian aquello a través de lo cual resuelve cada proyecto de esa máquina, incluidos proyectos que nadie en esta sesión ha nombrado. Ambas respuestas llevan scope, con el configFile que se escribió y machineWide, que indica si es el compartido. La eliminación es la más delicada de las dos, porque volver a añadir no es el mismo acto — la política de confianza que estaba fijada ha desaparecido, y un registro posterior fija lo que el registro anuncie entonces.
Inicializar una configuración escribe ese mismo archivo compartido de forma predeterminada, y por la misma razón. aggrega/configInit registra un registro y su política de confianza, que son herramientas de toda la máquina, así que sin anulación escribe la configuración a través de la cual resuelve cada proyecto de la máquina — y alcanza ese registro una vez para leer la política que anuncia. Su respuesta lleva el mismo par scope que llevan los dos métodos de registro. Se diferencia de ellos en un aspecto en el que conviene confiar: se rechaza en lugar de sobrescribir un archivo de configuración existente, así que no puede sustituir una configuración con la que alguien está trabajando salvo que la solicitud envíe force. Congelar es el caso opuesto: aggrega/configCapture no acepta ninguna anulación, siempre escribe el archivo de configuración propio del proyecto y no alcanza ningún registro, así que nada de lo que hace es visible para otro proyecto. Consulta Qué deja tras de sí una escritura de configuración.
🔴 Añadir o eliminar un plugin de extensión de comandos escribe ese mismo archivo compartido de forma predeterminada, y este es el caso que hay que leer con atención. aggrega/pluginAdd y aggrega/pluginRemove aceptan un type, y el tipo decide adónde va la escritura cuando no se envía ninguna anulación. Una entrada provider, governance, linter o importer da forma al build de un proyecto, así que va a la configuración propia de ese proyecto. Una entrada cli es una herramienta de toda la máquina, así que una adición de tipo cli que no nombra ni global ni workspace registra el comando en el archivo de configuración global a través del cual resuelve cada espacio de trabajo de esta máquina — el comando pasa a ser un comando aggrega de primer nivel para cada proyecto de esa máquina, incluidos proyectos que nadie en esta sesión ha nombrado, y retirarlo es una eliminación aparte en lugar de un deshacer. Envía workspace: true para mantenerlo local. Ambas respuestas llevan scope, con el configFile que se escribió y machineWide, que indica si es el compartido, derivado del archivo en el que se resolvió la escritura. Una adición también alcanza el registro en el que buscó, así que está en ambos ejes a la vez. Consulta Qué te dice un cambio de plugin.
Las otras dos solicitudes de plugins escriben solo dentro del espacio de trabajo. aggrega/pluginSync escribe el archivo de entidad Plugin que nombra la solicitud, y aggrega/pluginGenCatalog escribe las entidades generadas bajo el outputDir que nombra la solicitud — ambas dentro del espacio de trabajo que nombró la solicitud, ambas rechazando un destino que sea absoluto o que se resuelva fuera de él, y ninguna visible para otro proyecto. aggrega/pluginGenCatalog lee su módulo y su capa superpuesta desde donde los seleccionaste, lo que no amplía dónde escribe: ambos se resuelven con reglas distintas, así que una generación puede leer un módulo que construiste en cualquier lugar mientras las entidades que produce siguen quedando dentro del espacio de trabajo. aggrega/pluginGenCatalog con dryRun no escribe nada en absoluto y devuelve el contenido en su lugar.
Fijar una entidad también escribe solo dentro del espacio de trabajo, y alcanza los hosts que nombran sus fuentes. aggrega/pin escribe el entity.lock junto a la entidad que nombra la solicitud, que es una ruta dentro del espacio de trabajo, y llena la caché de contenido del espacio de trabajo con las fuentes que obtuvo; nada de lo que escribe es visible para otro proyecto. Sale al exterior para resolver cada fuente remota que nombra la entidad — un repositorio de charts, un host de Git, una URL — que es el mismo alcance que tiene aggrega/resolveDependencies para las fuentes que consume una Release. aggrega/resolveDependencies y aggrega/publishEntity enviadas con pinSources ejecutan este mismo paso, así que cada una de ellas escribe también junto a las entidades que fija; una publicación que fija alcanza por tanto el espacio de trabajo además del registro. Una publicación que no fija no escribe nada junto a la entidad, y aun así alcanza esos hosts: comparar el lock con lo que registraría el paso implica obtener cada fuente remota que la entidad escribe completa.
Instalar el skill del asistente se queda dentro del espacio de trabajo salvo que la solicitud envíe global. aggrega/skillsInstall escribe la carpeta de skills de proyecto de cada asistente nombrado dentro del espacio de trabajo que nombró la solicitud, y nada de lo que escribe allí es visible para otro proyecto; el scope de su respuesta lleva machineWide en false. Con global: true escribe en cambio la carpeta por usuario de cada asistente bajo el directorio personal, que ese asistente lee en cada proyecto de la máquina, y machineWide es true. En ambos casos no alcanza ningún registro ni ninguna red.
Eliminar una credencial almacenada llega más lejos que cualquier otra cosa de aquí que se detiene en esta máquina. aggrega/logout cambia el almacén de credenciales, y ese almacén lo comparten no solo todos los proyectos de la máquina sino todas las demás herramientas que se autentican en los mismos registros — así que una credencial eliminada a través de una sesión desaparece para todos ellos, y aggrega/registryList la informará como ausente también en cada otro espacio de trabajo. Su respuesta lleva scope con machineWide, que siempre es true: este almacén no tiene ninguna forma limitada al espacio de trabajo en la que resolverse, así que no hay ninguna anulación que enviar ni nada a lo que una solicitud pueda optar. scope no nombra deliberadamente ningún archivo, a diferencia de las escrituras de configuración de arriba. El almacén delega en el asistente de credenciales o el llavero del sistema operativo que la máquina tenga configurado, así que la eliminación la sirve con frecuencia algo que no es un archivo en absoluto, y nombrar una ruta te señalaría una ubicación que la eliminación no tocó necesariamente.
La eliminación no es lo contrario de autenticarse, y un cliente no debería ofrecerla como tal. Esta superficie elimina una credencial y no adquiere ninguna: recuperar una credencial implica autenticarse de nuevo con aggrega login en una terminal, porque almacenar una requiere un secreto escrito por una persona y nadie está observando este flujo. Así que un «cerrar sesión» que ofrezca un cliente es, desde aquí, de un solo sentido. Lo que separa las dos operaciones es si la operación tiene que obtener algo de quien la dirige — una eliminación lleva su único valor en la solicitud, mientras que adquirir una credencial no — y no si interviene una persona, ya que una persona eligió ambas.
Liberar contenido de la caché también va más allá del espacio de trabajo. Los almacenes de módulos compilados y de descripciones de plugins los comparten todos los proyectos de la máquina, así que aggrega/cachePrune, aggrega/cacheEvict y aggrega/cacheClear pueden eliminar contenido del que depende otro proyecto. Cada eliminación lleva el reach de la clase de la que procede, y cada respuesta lleva scope.machineWideClasses. aggrega/cacheStatus lleva el mismo alcance en cada clase aunque no cambie nada, porque un cliente que decide si liberar espacio lo necesita antes de actuar.
Actualizar el índice de búsqueda es el caso contrario. aggrega/registryUpdate alcanza cada registro configurado, y lo que escribe queda bajo el directorio de caché configurado propio de este espacio de trabajo — así que no cambia nada a través de lo cual resuelva otro proyecto. indexRoot en la respuesta nombra ese directorio.
Una actualización parcial responde en lugar de fallar. Una solicitud que nombra un registro cuya actualización falló es un error, porque no hay respuesta que dar. Una solicitud que actualiza cada registro configurado tiene éxito incluso donde algunos de ellos, o todos, fallaron: los actualizados se indexaron y escribieron, failed nombra el resto y cada host lleva su propio error. Lee failed en lugar de la presencia de un error.
Si se pudo llegar a un registro es una clave, no una interpretación del mensaje. Un host que falló lleva unreachable: true donde nunca se llegó al registro — su nombre no se resolvió, una conexión con él se rechazó o no se pudo abrir, o no se pudo establecer con él una conexión segura — y el rechazo de una solicitud que nombra un registro lleva la misma clave en su data. Un registro al que se llegó y que falló, con un listado que se repetía o un estado de error, no la lleva en ninguno de los dos casos, y su error, o el mensaje del rechazo, dice qué respondió. La clave se lee del propio fallo, así que no depende de cómo formule un fallo el resolutor de esta máquina, y se establece solo donde el fallo muestra que nunca se llegó al registro: un fallo que no muestra nada en ningún sentido, como un límite de tiempo agotado sin constancia de qué paso interrumpió, se informa sin ella. Indica que no se llegó a un registro basándote en la clave, y muestra el error como motivo.
La línea de comandos informa de ese mismo recorrido como una salida distinta de cero, y qué tipo de lector eres decide cuánto vale esa salida. Para una persona ante una terminal no es la información completa: aggrega registry update imprime cuántos de los registros seleccionados indexó, qué encontró cada uno, cuáles no indexó y dónde se escribió el índice — así que el resumen dice qué pasó y el estado de salida dice solo si todo tuvo éxito. Para un script es la información completa, porque ese comando no ofrece ningún modo de salida estructurada, así que su estado de salida es el único veredicto legible por máquina disponible. Por eso las dos superficies responden de forma distinta al mismo recorrido parcial y ambas tienen razón: esta entrega failed a un llamador estructurado y tiene éxito, mientras que la línea de comandos tiene un solo bit que gastar y lo gasta en «se omitió algún registro».
Seguir una operación larga
La mayoría de las solicitudes de aquí responden a partir de lo que ya está en disco y responden de inmediato. Unas pocas hacen primero un trabajo real — resolver las dependencias de una Release, fijar sus entradas externas, publicar, firmar, retirar — y el llamador espera. Esas informan de lo que están haciendo mientras lo hacen, y se activa de forma explícita en cada solicitud.
Activarlo requiere dos pasos, en este orden.
- Declara la capacidad en el handshake y espera la respuesta. Envía
capabilities.window.workDoneProgress: trueenaggrega/initialize. No envíes nada más hasta que haya llegado esa respuesta: las solicitudes se atienden de forma concurrente, así que una solicitud escrita antes de que respondiera el handshake puede estar ejecutándose junto al handshake que debía negociar por ella. Todo cliente ya le debe al protocolo ese orden; esto es una cosa más que depende de él. - Pon un token en los params de la solicitud. Añade
workDoneTokena los params de la solicitud sobre la que quieres recibir informes. El valor lo eliges tú — una cadena o un número — y es lo que vincula las notificaciones a esa llamada. Genera uno nuevo para cada llamada.
La notificación. Cada una es $/progress con params.token establecido en tu token y params.value llevando una carga útil:
value.kind | lleva | cuándo |
|---|---|---|
begin | title — qué está ocurriendo, en una frase que puedes poner ante un lector | una vez, cuando empieza el trabajo |
report | message — una línea del propio relato que la operación hace de sí misma | cualquier número de veces, a medida que la operación las escribe |
end | nada más allá del tipo | una vez, cuando el trabajo ha terminado |
Correlaciona por el token, nunca por el id de la solicitud. Una notificación no lleva ningún id — no es una respuesta a nada — y el token es lo único en ella que remite a tu llamada. Es deliberado: en muchos clientes el id de la solicitud pertenece al transporte y nunca llega al código que emitió la llamada, mientras que el token es un valor que ese código ya tiene.
Un report lleva el propio texto del compilador. El mensaje es una línea que la operación escribió mientras trabajaba, transmitida con los espacios que la rodean eliminados y nada más cambiado — ni reformulada, ni resumida, ni recompuesta — y una línea que la operación escribió vacía se descarta en lugar de informarse como un mensaje vacío. Así que un cliente muestra lo que recibe tal cual. Es la misma propiedad que tienen los propios diagnósticos de la respuesta: una condición mantiene una sola redacción por muchas superficies que la informen.
Un paso que la operación espera también es un report. Cuando la operación entra en un paso que espera —leer un registro, obtener un artefacto, compilar un plugin—, un report lleva el nombre del paso, con las palabras que la línea de comandos muestra junto a su indicador de progreso para ese mismo paso. Solo se informa de los pasos en los que se entra entre el begin y el end.
Una línea de salida es un report. Una operación que escribe varias líneas a la vez produce una notificación por línea, y una línea que la operación escribe por partes se informa una vez completa — así que un mensaje nunca es media frase.
No hay fracción ni porcentaje, y no es una omisión pendiente de trabajo. Las operaciones que informan aquí recorren un conjunto cuyo tamaño no se conoce cuando empieza el trabajo — cuántas referencias recorre una resolución, cuántas capas sube una publicación — así que cualquier fracción sería inventada. Dibuja un indicador indeterminado y muestra el último message.
Los frames llegan antes de la respuesta y nunca después. Un begin llega una vez que el trabajo ha empezado realmente, así que una solicitud rechazada por sus params — una ruta absoluta, un campo obligatorio que falta — no produce ninguna notificación, solo su error. El end llega antes de la respuesta, y si la operación tuvo éxito figura en la respuesta en lugar de repetirse en el end.
Detener el trabajo es una notificación aparte. Envía $/cancelRequest con el id con el que enviaste la solicitud. El token no interviene en la cancelación, y cancelar no suprime los frames ya enviados.
Qué solicitudes informan, y qué esperar del resto
Informan exactamente estas: aggrega/resolveDependencies, aggrega/pin, aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact.
Dos cosas son ciertas de cada una de ellas, y ambas son el motivo de que esté en la lista: alcanza un registro o una URL remota en tu nombre, así que cuánto tarda lo determina algo fuera de la máquina; y ya escribe su propio relato de sí misma a medida que avanza — el relato que lee una persona que observa una terminal. Así que el informe te entrega ese mismo relato en lugar de un segundo compuesto para la transmisión, y nada de lo que hace la operación tuvo que cambiar para producirlo.
Cualquier otra solicitud acepta un token y no envía nada. Enviar uno es inofensivo y no un error: se acepta, no llega ninguna notificación y la respuesta es exactamente la que habrías obtenido sin él. Así que un cliente puede adjuntar un token a lo que quiera y simplemente no dibujar nada cuando no llegue nada.
🔴 No interpretes el silencio como «esta es instantánea». La mayoría de las demás sí responden a partir de lo que ya está en disco — una validación, un hover, un autocompletado, un grafo, un listado de la caché, una lectura de configuración — pero no todas: actualizar el índice de un registro, añadir un plugin, una comprobación previa a la publicación y la primera explicación de un código en una máquina que no tiene documentación que el espacio de trabajo pueda leer alcanzan todas un registro, y compilar una Release es trabajo real. Esas tardan lo que tardan y hoy no informan de nada. Muestra un indicador indeterminado para cualquier solicitud que estés dispuesto a esperar, y trata las notificaciones como un detalle que obtienes cuando está disponible y no como lo que te dice que hay trabajo en curso.
Dos rechazos
Ambos son errores invalid-params y ambos nombran qué hacer, porque un token que en silencio no hiciera nada te dejaría esperando un flujo que nunca iba a llegar.
- Un token de una sesión que no declaró ninguna capacidad
window.workDoneProgressse rechaza, nombrando la capacidad que hay que declarar. Declárala en el handshake, u omite el token. - Un token que no es ni una cadena ni un número se rechaza, nombrando las dos formas. Un token ausente, y un
nullexplícito, no son rechazos — ambos significan que no pediste ningún informe.
Conocimiento del lockfile
El daemon comprueba la deriva de un lockfile en cada aggrega/irGraph, con respecto a la Release que nombró esa solicitud, y muestra la deriva como una advertencia no bloqueante. La advertencia nombra el comando que reescribe ese lockfile con la Release en él, escrito tal como lo envió la solicitud — aggrega pull --release seguido del release que enviaste, que es como se escribe en una terminal en la raíz del espacio de trabajo. aggrega/irGraph requiere que haya un lockfile presente. No hay ninguna comprobación aparte al arrancar: una solicitud dice de qué Release se trata, así que el veredicto se calcula para esa Release cuando se pide y no una sola vez para una Release elegida de antemano.
Una advertencia de deriva desaparece cuando desaparece su lockfile. La advertencia se publica sobre el lockfile con respecto al cual se emitió, y un lockfile que ya no está no tiene pins que puedan haber derivado — el comando que nombra la advertencia escribiría un archivo nuevo en lugar de reparar el antiguo. Así que cada solicitud que encuentra que falta el lockfile retira la advertencia antes de rechazarse con el error de lockfile ausente: aggrega/irGraph, aggrega/releaseClosure, aggrega/build, aggrega/buildPreview, aggrega/attachCandidates y aggrega/attachmentContainer consultadas sobre un nodo del grafo, y aggrega/connectionAtPosition. La retirada llega como una notificación aggrega/publishDiagnostics para el lockfile con una lista vacía, antes del rechazo. Procede de la primera de esas solicitudes que se entere del borrado, así que a un cliente que informa del borrado y luego pide cualquier cosa sobre esa Release se le borra la advertencia sin tener que pedir específicamente el grafo. Un lockfile que sigue presente y sigue con deriva mantiene su advertencia a lo largo de cada una de esas solicitudes. aggrega/invalidate que nombra el lockfile descarta lo que el daemon guarda de él pero no envía nada; es la solicitud siguiente la que informa al cliente. Y un lockfile que el daemon ni siquiera puede examinar — uno cuyo directorio no puede leer, por ejemplo — no retira nada, porque puede que siga ahí y puede que la advertencia siga siendo cierta.
aggrega/build y aggrega/buildPreview también requieren uno, y sujetan la Release a él en lugar de advertir — renderizan con la postura de una superficie que emite un artefacto, así que un lockfile que ya no coincide con aquello en lo que se resuelve la Release los detiene donde en una inspección solo advertiría. Una Release sin lockfile se rechaza con el error de lockfile ausente. La excepción es un build cuyo campo autoPull le pide resolver primero las dependencias: ese build escribe el lockfile y luego renderiza con respecto a lo que escribió, y un lockfile producido de esa manera no se comprueba por deriva una segunda vez, porque la resolución que lo escribió ejecutó la misma comprobación sobre él antes de escribirlo y no escribe ningún lockfile que esa comprobación rechace.
Un lockfile que existe pero no registra ningún digest para un plugin no detiene el grafo — un lockfile ausente sí. Son dos condiciones y solo la segunda provoca un rechazo. aggrega/irGraph no sujeta los bytes que resuelve a sus digests registrados: un pin que no puede verificar se informa en lugar de rechazarse, y el grafo se dibuja con el hallazgo en el panel Problems, ya que un editor que se niega a dibujar el grafo deja al lector sin nada, mientras que un informe le deja algo sobre lo que actuar. En otros lugares el plugin también se ejecuta, con una advertencia que dice que nada comprobó sus bytes. Lo que aggrega/irGraph rechaza es el lockfile que falta: se detiene antes de resolver nada y responde con el error de lockfile ausente, nombrando el lockfile que buscó y la Release, de modo que un cliente puede ofrecer directamente aggrega pull --release <release> — o enviar aggrega/resolveDependencies para esa Release y escribir el lockfile sin salir de la sesión. Mantener ambas cosas separadas importa, porque un grafo dibujado es una imagen sobre la que luego razona un lector, y uno construido a partir de bytes que nada comprobó se dibuja exactamente igual que uno comprobado, con el hallazgo en algún lugar donde el lector no está mirando. Así que un grafo no es un veredicto sobre los bytes que hay detrás — aggrega/build y aggrega/buildPreview son las superficies que sujetan una Release a sus digests registrados, deteniéndose donde la inspección se limita a informar.
aggrega/validate, cuando una solicitud nombra una Release, lee el lockfile de esa Release solo para sus pins y sus avisos de obsolescencia — y no lee ninguno para una entidad de catálogo que comprueba como entidad individual, igual que la línea de comandos no lee ninguno. No sujeta los plugins que ejecuta a los digests registrados, y no reconstruye a partir del lockfile el conjunto de adjuntos de los plugins de transformación — valida con respecto a la configuración del espacio de trabajo tal como está delante de ti, que es lo que un editor tiene que hacer mientras editas esa configuración. aggrega validate y aggrega build hacen ambas cosas, y siguen siendo las superficies de referencia para un veredicto sobre un espacio de trabajo confirmado.
Sus avisos de obsolescencia cubren los dos lugares donde se registra una retirada. Un marcador sobre una referencia fijada está en el lockfile; un marcador sobre un plugin adjuntado en un rol que devuelve un veredicto de aceptación o rechazo — un adjunto plugins.governance en ir-verdict o render-verdict, o un adjunto plugins.linter — está en el registro de confianza de plugins a su lado, así que la validación lee ambos y nombra cada referencia retirada y cada plugin retirado como una advertencia al principio del Aggregate, con las palabras que imprime aggrega build. Un aviso no cambia ningún veredicto. Un registro de confianza que existe y no se puede leer se informa como un error en lugar de la validación, en vez de leerse como uno que no registra nada. aggrega/releaseClosure informa del mismo conjunto en su deprecations.
Dónde está el lockfile de una Release
Cada respuesta que nombra una Release nombra también su lockfile, así que un cliente nunca tiene que deducir la ruta. aggrega/activeRelease lo lleva como lockfile junto a release, aggrega/releaseCandidates como el mapa lockfiles junto a releases, y el error de lockfile ausente como lockfile en su data. Cada uno es el archivo que aggrega pull --release <release> escribe y aggrega build lee, y el archivo que busca cada solicitud de arriba — así que un cliente que vigila el lockfile de una Release, para notar que se escribe, se reescribe o se borra, vigila el archivo al que se refiere el daemon. El lockfile está junto a su Release y toma el nombre de la Release con una extensión .yaml o .yml sustituida por .lock; una Release nombrada con cualquier otra extensión conserva su nombre completo, así que el lockfile de release.rel es release.rel.lock. Lee la ruta de la respuesta en lugar de componerla a partir de esa descripción, y ambas no podrán divergir.
Las referencias externas que pide un renderizado
Un renderizado puede pedir contenido de una URL remota — el esquema de valores de un chart con una referencia remota, por ejemplo. Las entradas externas se congelan en cada renderizado que este daemon realiza en respuesta a una solicitud que solo pedía que se le informara de algo. Una referencia que el lockfile de la Release fija se sirve desde el almacén direccionado por contenido, lo cual es una lectura de contenido que ya está en disco y no una descarga, y se comprueba contra lo que registra el lockfile antes de servir sus bytes — así un renderizado aquí ve lo que ve un build y emite los avisos que emite un build. Una referencia que el lockfile no fija se rechaza en lugar de descargarse: adquirirla supondría acceder a una red y escribir un blob en el almacén, y una sesión no hace ninguna de las dos cosas ante una solicitud que solo pedía que se le informara de algo. Esa es la regla de Acceder a un registro y escribir vista desde el lado del renderizado, y se aplica sea cual sea la forma en que se llegó a ese renderizado.
La solicitud que existe para fijar es la excepción, y es la misma excepción que ya contempla la regla del registro. A aggrega/resolveDependencies se le pide que adquiera, por lo que el renderizado que realiza para descubrir qué referencias consume esta Release accede a la red y escribe lo que fija — que es lo que hace que su resultado sea un lockfile y no un informe. Ningún renderizado que una solicitud de grafo o de build realice por su cuenta hace nada de eso.
Un build al que se le pide resolver primero se responde a partir de ese mismo renderizado, y por eso renderiza la Release una sola vez. La resolución ya ha renderizado aquello de lo que trata el build, contra los pines que acaba de escribir y bajo las comprobaciones que ejecuta un build, por lo que el build presenta ese renderizado en lugar de realizar un segundo — y la adquisición sigue correspondiendo a la resolución y no al build. Solo un renderizado que terminó se usa de ese modo: cuando una resolución fijó sus dependencias pero no pudo terminar de descubrir las referencias externas, el build renderiza por su cuenta contra los pines que sí se escribieron, y una referencia no fijada se rechaza y se notifica allí exactamente igual que en un build que no resolvió nada.
El rechazo se notifica en lugar de absorberse, porque nada en un resultado indica qué referencia le faltaba. Con los providers que incluye este binario, el provider que pidió la referencia devuelve el rechazo, por lo que un renderizado que llegó a una referencia rechazada no se completa. Por eso cada referencia rechazada llega como una entrada propia en la capa aggrega-build, que nombra la referencia y el comando que la fija: aggrega pull --release <release>, o aggrega/resolveDependencies para el mismo trabajo sin salir de la sesión. Las entradas son consultivas y no un rechazo — el grafo se devuelve igualmente, con la misma consideración que tiene el aviso de deriva anterior — y se atribuyen al Aggregate que encabeza el archivo, porque una referencia que pidió un renderizado no nombra ninguna clave que haya escrito un autor. Viajan en la misma publicación que los avisos propios del renderizado, que sustituye esa capa por completo, de modo que una referencia que luego fijes deja de notificarse sin que nada tenga que borrarla. Un renderizado totalmente fijado no dice nada de todo esto. Consulta Qué contiene una entrada de diagnóstico para ver la forma que adopta cada entrada.
En aggrega/irGraph, esto depende de que la etapa de renderizado se ejecute. La solicitud de grafo omite el renderizado a menos que --build-on-inspect, o la clave serve.build_on_inspect que este sobrescribe, lo active; con el ajuste desactivado, nada pide una referencia externa y no hay nada que rechazar. Activarlo es lo que lleva a una sesión del editor tanto los avisos propios del renderizado como estos.
En qué se diferencia una sesión del mismo congelamiento en la línea de comandos. aggrega build también congela las entradas externas en una ejecución de prueba, y una referencia no fijada se comporta igual en ambas superficies: se notifica como un hallazgo que nombra la referencia, y luego el renderizado se detiene, porque el provider que la pidió devuelve el rechazo. Lo que difiere es la nueva descarga. En la línea de comandos, una referencia fijada cuya copia almacenada ha desaparecido se vuelve a descargar por su digest registrado; el renderizado que responde a una solicitud de grafo o de build no vuelve a descargar nada, porque ese renderizado no accede a ninguna red, así que no puede volver a buscar una referencia fijada que el almacén ya no contiene — y esa referencia no está entre los rechazos descritos antes, que nombran lo que el lockfile no fija. Pedir a una sesión que fije es lo que la recupera: las solicitudes nombradas antes acceden a la red y reponen los bytes que faltan. Consulta aggrega pull para saber qué descarga y registra la fijación.
Lo que una ejecución rechazada aún te dice
Una solicitud que rechaza responde con un sobre de error, y los hallazgos que la ejecución ya había hecho no viajan dentro de ese sobre — el sobre no lleva ningún cuerpo de resultado. Te llegan del mismo modo que en una ejecución que terminó: como una publicación de diagnósticos en la capa aggrega-build, descrita en Qué contiene una entrada de diagnóstico. Así, un cliente que gestiona un rechazo lee el sobre para saber qué cambiar y su superficie de problemas para saber qué encontró la ejecución, y ninguno sustituye al otro. Un rechazo emitido durante el renderizado es el único rechazo que es también un hallazgo sobre lo que escribió un autor, por lo que llega a ambos, como describe la sección siguiente.
Esa publicación se produce tanto si la ejecución llegó a su fin como si no. Una ejecución que se detiene a mitad de camino encontró igualmente todo lo anterior al punto en que se detuvo, y un lector que perdiera esos hallazgos tendría que volver a ejecutarla para verlos — por eso los avisos se publican a partir de lo que alcanzó la ejecución, y el rechazo se devuelve después. Es el mismo conjunto con la misma fidelidad, situado en las mismas claves de autoría: un rechazo no rebaja un hallazgo a una frase. Las referencias externas rechazadas viajan en esa misma publicación, por la misma razón y por la misma vía.
Lo que la limita es hasta dónde llegó la ejecución, no lo que la capa puede llevar. Un rechazo de una de las comprobaciones que se ejecutan antes de que arranque el compilador — no se pudo resolver el cierre de la Release, el Manifest asigna un tipo a una receta que no lo implementa, el lockfile ya no coincide con aquello en lo que se resuelve la Release, una entrada fijada en la caché ya no coincide con el digest registrado para ella y ningún directorio del catálogo contiene los bytes fijados — no tiene avisos que publicar, porque todavía no se había emitido ninguno. La capa entonces no lleva nada en lugar de algo obsoleto; y una ejecución que no llegó a nombrar un documento no publica nada en absoluto, y deja lo que ya está en tu superficie de problemas exactamente como estaba en lugar de borrar entradas de las que no supo nada.
Un rechazo emitido durante el renderizado
Una Release que el compilador rechaza mientras la renderiza — un Workload que nombra un slot que su Component no declara, una aserción que falla, una plantilla que no se puede evaluar, una realización que no aporta lo que debe aportar — se notifica donde apunta y con las palabras del compilador, en cada solicitud que la renderiza: aggrega/build, aggrega/buildPreview y aggrega/irGraph con la etapa de renderizado activada. La respuesta es un sobre de error con el código -32603, cuyo message es el rechazo con cada causa debajo, con las palabras que la línea de comandos imprime para el mismo build: el nodo que se está renderizando, luego lo que en él rechazó, cada causa después de la que explica — encabezado, cuando el rechazo nombra una condición registrada, por el código corto de esa condición, como lo está todo rechazo que nombra una. Su data nombra el documento al que apunta el rechazo como file, y el intervalo de la clave en él como line, column, end_line y end_column, junto a code y shortCode de la condición; un rechazo que no nombra ninguna clave, o una que el documento no contiene, lleva solo file, y uno que no apunta a ningún documento nombra el Aggregate de la Release.
El mismo rechazo se publica en la capa aggrega-build, en ese documento, en esa clave, como una entrada de severidad error que lleva el keyPath propio del rechazo y el message del sobre sin el código corto delante, y — cuando el rechazo nombra una condición registrada — code, shortCode y codeDescription de esa condición, con el código corto viajando allí en su propio campo. Viaja en la única publicación que lleva los avisos que la ejecución emitió antes de detenerse, por lo que sustituye la capa como lo hacen ellos: la siguiente ejecución de la Release que renderiza publica la capa sin él, y el documento en el que estaba se publica vacío, que es lo que lo borra de tu superficie de problemas.
El lugar al que apunta un rechazo es lo que el propio rechazo nombra, y nada más preciso. Las comprobaciones de un Workload juzgan el documento que produjo su plantilla, y una plantilla puede escribir líneas que ningún autor escribió — un bucle, una condición, un texto importado de un archivo o de una biblioteca —, por lo que una línea del Workload renderizado no se corresponde con una línea de la Recipe. Por eso un rechazo sobre un Workload se sitúa en la clave workload de la Recipe, y las rutas que nombra dentro del documento renderizado permanecen en su mensaje. Una aserción que falla se sitúa en su propia clave bajo assertions en la Recipe o la FeatureRecipe que la declara; una aserción que declara un Component o una Feature se emite antes de que haya un documento disponible que nombrar, y se sitúa en la clave kind: del Aggregate. Un rechazo de un paso que nombra un documento pero ninguna clave se sitúa en la clave kind: de ese documento.
Un rechazo que reúne varios hallazgos se publica hallazgo por hallazgo. La composición del grafo con el que trabaja el renderizado rechaza con todas las infracciones que encontró en un solo rechazo — una entrada que nombra un destino al que nada responde, dos conexiones de un componente con el mismo alias — y la línea de comandos imprime cada una como un diagnóstico propio, bajo su propio encabezado. Aquí cada una es una entrada propia en la capa aggrega-build, en el documento y en la clave que nombra ese hallazgo — la Release donde lo escribió la Release, el Aggregate donde lo hizo el Aggregate —, con sus propias palabras y sus propios códigos. El message de la respuesta lleva todos los hallazgos, y su data nombra adónde apunta el primero.
Un valor que un autor declaró sensible se oculta aquí exactamente igual que lo oculta la línea de comandos. El texto del rechazo es el texto que emitió el compilador, nada en esta superficie lo reformula, y el compilador oculta un valor declarado allí donde se emite el rechazo — <redacted> en su lugar —, por lo que esta respuesta, esta entrada y el terminal lo muestran con las mismas palabras; qué dice un rechazo sobre un valor declarado explica cómo, y qué rechazos quedan fuera.
Un rechazo de una comprobación que se ejecuta antes del renderizado no es esto. Las comprobaciones enumeradas antes responden como describe Lo que una ejecución rechazada aún te dice. Una aserción que declara un Component o una Feature, y un rechazo sobre el grafo compuesto, quedan entre ambos: cada uno se emite antes del renderizado, en cada solicitud que resuelve el grafo de una Release, por lo que aggrega/irGraph lo responde y lo publica como se indicó también con la etapa de renderizado desactivada; aggrega/releaseClosure, aggrega/attachCandidates y aggrega/attachmentContainer consultados sobre un nodo del grafo, y aggrega/connectionAtPosition, lo responden con el mismo sobre y no publican nada, porque no tienen ninguna superficie de problemas.
Códigos de error
Las respuestas usan los códigos de error estándar de JSON-RPC más un rango propio de la aplicación en la banda 1xxx. Un cliente de editor puede ramificar según el código sin analizar el mensaje.
1001file-not-validated (archivo no validado) — el daemon no tiene nada para el archivo, tal como está ahora, a partir de lo cual pueda responder la solicitud: ningún análisis del archivo o, paraaggrega/diagnostics, ningún análisis del archivo o nada guardado para el archivo que sea la respuesta de una validación para el texto que el daemon tiene ahora. Envíaaggrega/validatepara ese archivo y vuelve a preguntar.1003lockfile-absent (lockfile ausente) — la Release que nombró la solicitud no tiene lockfile, y la operación pedida necesita uno.1004entity-not-resolvable (entidad no resoluble) — el nombre no coincidió con ninguna entidad en ningún nivel del catálogo, ni en la Release que nombró la solicitud; o la referencia de registro enviada como nombre no se pudo leer como una entidad, y el mensaje nombra la condición que explica por qué; o el lockfile de la Release es un enlace que sale del espacio de trabajo, lo cual se rechaza antes de que nada lo lea, condatanombrando el lockfile y la Release y el mensaje empezando por el código corto de la condición,E0321— consulta el límite del espacio de trabajo.1005shutting-down (cerrándose) — el daemon se está vaciando tras una notificación de apagado y rechaza las solicitudes nuevas. No reintentes contra el mismo subproceso.1006validation-in-flight (validación en curso) — hay una validación del archivo en ejecución que no terminó dentro del margen que le concedió la solicitud en espera. Vuelve a preguntar en breve y no envíes nada.
1002 no está asignado, y está disponible para la próxima condición que necesite un código.
File-not-validated y validation-in-flight informan de estados opuestos, y la acción que pide cada uno también es la opuesta. File-not-validated significa que el daemon no tiene nada para el archivo, tal como está ahora, a partir de lo cual pueda responder la solicitud — ningún análisis del archivo o, para aggrega/diagnostics, ningún análisis del archivo o nada guardado para el archivo que sea la respuesta de una validación para el texto que el daemon tiene ahora: envía aggrega/validate y vuelve a preguntar. Una validación cancelada a medias deja un archivo en esa situación, porque no almacena nada y lo que una validación anterior encontró sobre un texto distinto no es una respuesta para el texto que el daemon tiene ahora; una respuesta anterior sigue siendo válida mientras el texto sea el que comprobó. Los hallazgos que el daemon envía sobre un archivo que él mismo leyó del disco — un lockfile que se desvió, una Release que no se carga — no son una validación del texto que tienes, así que tampoco responden a esta solicitud. Dos validaciones de textos distintos enviadas con poco intervalo también pueden dejarte en esa situación, cuando la validación cuyo texto conservó el daemon terminó primero: la solicitud se rechaza aunque ese texto se comprobó, y validar de nuevo la responde. Se formula en términos del análisis y no del archivo porque un búfer que ningún analizador leerá está exactamente en esa situación — la validación se ejecutó e informó de lo que encontró, y sigue sin haber un análisis a partir del cual responder. Validation-in-flight significa que hay una validación suya en ejecución que no terminó dentro del margen que le concedió la solicitud en espera: vuelve a preguntar en breve y no envíes nada, porque el estado que necesitas ya está en camino y una segunda validación solo añadiría trabajo. Leer ambas como una sola condición lleva a un cliente a enviar una validación justo en el caso en que enviarla es el paso equivocado. Las dos bandas significan cosas distintas para un cliente: un código 1xxx nombra un estado del espacio de trabajo sobre el que el usuario puede actuar — validar el archivo, generar el lockfile —, mientras que un código estándar como invalid-params nombra una solicitud mal formada, que corrige el cliente y no el usuario. Un valor release presente pero mal formado — absoluto, o que se resuelve fuera de la raíz del espacio de trabajo — cae en la segunda banda: no es el espacio de trabajo el que está en un estado que el usuario debe reparar, sino la solicitud. Omitir release no está en ninguna de las dos bandas, porque no es un error en absoluto; selecciona la más restringida de las dos respuestas descritas en Validación en vivo.
Un error puede llevar un objeto data, y cada clave que contiene nombra una cosa y solo esa. file es el documento de origen al que se refiere el fallo — el documento que se valida, la Release cuya carga falló, el documento del espacio de trabajo que declara un nombre que nada resolvió, o el documento al que apunta un rechazo emitido durante el renderizado —, y es aquello dentro de lo cual los line y column que lo acompañen localizan una posición. Esos dos son a su vez opcionales: un fallo sobre un documento entero lleva solo file. lockfile es un lockfile. release es la Release a la que se refiere el error, escrita como la nombró la solicitud, para que un cliente pueda componer aggrega pull --release <release> sin tener que extraerla del mensaje. unreachable indica que no se pudo acceder al registro que nombró una solicitud rechazada: la lleva una actualización de índice rechazada que nombra un registro, leída del propio fallo, y un registro que respondió la deja ausente. Cada clave es opcional y está presente solo cuando el daemon tiene ese valor a mano; ninguna sustituye a otra, por lo que aquello a lo que apunta una clave nunca depende del código que la acompaña.
code y shortCode en data nombran la condición que informa un rechazo, en todo rechazo que informa de una registrada, sea cual sea su código numérico: el código descriptivo según el que ramifica un programa y el código corto que cita una persona, los mismos dos identificadores, con los mismos nombres, que lleva una entrada de diagnóstico para la misma condición, y enumerados en la tabla de todas las condiciones. Ramifica según code. El código numérico nombra el estado de la solicitud y sigue siendo el mismo para muchas condiciones — un build rechazado porque un enlace del catálogo sale fuera y un build rechazado porque un nombre no se resuelve en nada son ambos 1004 — y el mensaje es prosa que puede reformularse, así que ninguno de los dos distingue una condición de otra. Invalid-params es uno de esos códigos compartidos: también lo provoca una solicitud que nombra un espacio de trabajo cuyo archivo de configuración sale fuera de él, y allí read-leads-out-of-workspace indica que el fallo está en la estructura del espacio de trabajo, que repara una persona, y no en la solicitud. Un rechazo que no informa de ninguna condición registrada no lleva ninguna de las dos claves, y las dos están presentes juntas o no lo están en absoluto. El mensaje de un rechazo que nombra una condición empieza por su código corto, E0321: …, una sola vez, que es la forma con la que se encuentra una persona al leerlo en todo rechazo de ese tipo; a un rechazo cuyo mensaje ya empieza por un encabezado entre corchetes que lleva el código — el informe de una línea sobre un documento del catálogo que la carga rechazó — no se le añade de nuevo.
El relato de cómo se ejecutó la cascada de Release del espacio de trabajo viaja en la respuesta de aggrega/activeRelease, en su campo trace, y no en un error: un espacio de trabajo que no apunta a ninguna Release es un estado normal y no una solicitud fallida. Es prosa de diagnóstico escrita para que la lea una persona, no una estructura que analizar. Muéstrala tal como está — escríbela en un registro o en un panel que el usuario pueda abrir — y no compares patrones con ella, no extraigas valores de ella ni ramifiques según las etiquetas que usa: su redacción, su disposición y esas etiquetas siguen la propia cascada y cambian cada vez que cambia la cascada. Un cliente que transmite el texto tal cual sigue funcionando a través de ese cambio; uno que ha aprendido su forma se rompe con él.
Véase también
- ../schema/other/serve-wire.md — las formas de los mensajes que intercambia este protocolo, generadas a partir del esquema publicado: el objeto de parámetros de cada método, cada resultado y cada carga útil de notificación, campo por campo.
- ./aggrega-build.md — el comando build, cuya canalización del compilador, comprobaciones y resolución de dependencias también ejecuta
aggrega/build, de modo que las dos superficies escriben un único árbol de salida y no dos. - ./aggrega-version.md — el comando version que usa una extensión del editor para comprobar la compatibilidad del daemon.
- ./aggrega-pull.md — el lockfile que lee la superficie de deriva del daemon.
- ./aggrega-lint.md — las convenciones de publicación que el daemon notifica a petición, y en cada validación una vez activado
serve.lint_on_validate.
Sinopsis
aggrega serve [flags]Descripción
Run the Aggrega compiler as a long-running service. The daemonreads JSON-RPC 2.0 messages from stdin and writes responses to stdoutunder the aggrega/ method namespace. State (parsed YAML, diagnostics,resolved catalog) holds across requests so IDE clients can issue manycheap operations without re-paying per-invocation startup cost.
The daemon resolves its workspace root through the same path everyaggrega command uses: --workspace-root when set (used as-is, validatedto exist as a directory), otherwise discovery walking upward from thecurrent working directory. A directory anchors the workspace when itholds a .aggrega-config.yaml carrying a workspace: block, or — as afallback — any of .aggrega/, aggregate*.yaml, release*.yaml,manifest*.yaml.
Configuration is the cascade composition of the .aggrega-config.yamlfiles from the workspace root down to the working directory (neareroverrides farther), beneath which the global config file — the one--config names, else the one the AGGREGA_CONFIG environment variablenames, else the default location when a file is there — and thebuilt-in defaults apply.
The daemon honors the aggrega/shutdown JSON-RPC notification for acooperative cross-platform exit: the daemon completes the in-flighthandler if any, refuses new requests with code 1005, and exitscleanly within a 2-second drain budget.
Asking the process itself to stop — an interrupt from the terminal, ora termination request from a supervisor or container runtime — takesthe same path on the same terms: the first request drains the daemonand it exits cleanly, and a second ends the process at once.Flags
| Flag | Predeterminado | Descripción |
|---|---|---|
--build-on-inspect | false | Ejecuta la etapa de renderizado de artefactos al inspeccionar un grafo IR, para que los avisos que aggrega build emite al renderizar aparezcan también como problemas en el editor. No añade ninguna de las comprobaciones en las que se detiene un build. No se escribe nada en disco: ni artefactos renderizados, ni directorio de salida, ni lockfile. Desactivado de forma predeterminada, en consonancia con aggrega inspect, que tampoco emite ningún aviso de este tipo. Si se establece, sobrescribe la clave de configuración serve.build_on_inspect. |