El entorno de trabajo

Se requiere la línea de comandos stxt (npm install -g @stxt-lang/cli, o npx @stxt-lang/cli sin instalar) y, para la sección 4, Visual Studio Code con la extensión stxt-lang.stxt. La sección 7 repite el recorrido en el playground, sin instalación. Todo lo que se usa aquí está descrito en Herramientas.

1. El proyecto y el directorio .stxt/

Un proyecto STXT es un directorio cualquiera con documentos .stxt. Lo único que añade STXT es un directorio llamado exactamente .stxt/ que contiene las gramáticas —esquemas y plantillas— del proyecto. Cuando una herramienta valida un documento busca ese directorio en el directorio del documento y en todos sus directorios ascendentes, y después en ~/.stxt y en /etc/stxt. Esa lista es la cadena de resolución del documento, y es la misma para el editor, la línea de comandos y cualquier otra herramienta: por eso un documento valida igual en todas partes.

Para el ejemplo, un proyecto libros con la gramática en .stxt/ y los documentos en docs/:

libros/
├── .stxt/            las gramáticas del proyecto
└── docs/
    └── book.stxt     los documentos

mkdir -p libros/.stxt libros/docs
cd libros

Dentro de .stxt/ se cargan todos los ficheros .stxt, recursivamente, y ni los nombres de fichero ni los subdirectorios tienen significado: son solo organización. Cada fichero debe ser una definición (@stxt.schema o @stxt.template); cualquier otro contenido dentro de .stxt/ es un error de resolución. Ver STXT-DISCOVERY-SPEC §3 y §4.

2. Escribir la gramática

La plantilla del libro es la del tutorial (sección 8). Se puede escribir directamente en .stxt/ con cualquier nombre, o dejar que la CLI la coloque: stxt install la parsea, comprueba que valida contra su meta-esquema y solo entonces la escribe, en forma canónica, como .stxt/@stxt.template/<namespace>.stxt. Esa nomenclatura es una convención de la CLI, no del lenguaje.

Template (@stxt.template): com.acme.book
	Structure >>
		Book:
			Title: (1)
			Authors: (1)
				Author: (+)
			ISBN: (1)
			Publisher: (?)
			Published: (?) DATE
			Summary: (?) TEXT
			Chapter: (+)
				Content: (?) TEXT
	Description >>
		Book: Plantilla para fichas de libros editoriales

stxt install book-template.stxt

Installed com.acme.book (@stxt.template) to /home/ana/libros/.stxt/@stxt.template/com.acme.book.stxt

stxt schemas muestra la cadena de resolución de un directorio, qué definición queda activa para cada namespace y de dónde procede:

stxt schemas docs

Resolution chain for /home/ana/libros/docs:
    /home/ana/libros/.stxt

Namespaces:
    com.acme.book <- /home/ana/libros/.stxt/@stxt.template/com.acme.book.stxt

Si el proyecto está dentro de otro que también tiene .stxt/ (un monorepo), la cadena incluye los dos directorios: ambos participan, y para cada namespace gana el más cercano al documento.

3. Escribir y validar el documento

El documento, en docs/book.stxt, con el namespace de la plantilla:

Book (com.acme.book):
	Title: Arquitectura de software moderna
	Authors:
		Author: María Pérez
		Author: Juan García
	ISBN: 978-84-123456-7-8
	Published: 2025-10-01
	Summary: Una introducción práctica a la arquitectura de sistemas modernos.
	Chapter: Introducción
		Content >>
			Conceptos básicos y objetivos del libro.

stxt validate docs/book.stxt

No escribe nada y termina con código 0: no hay salida cuando todo pasa. Para observar los hallazgos, dos errores típicos: una fecha que no es YYYY-MM-DD y un nodo obligatorio que falta. Con Published cambiado a texto libre y sin la línea ISBN:

Book (com.acme.book):
	Title: Arquitectura de software moderna
	Authors:
		Author: María Pérez
		Author: Juan García
	Published: 1 de octubre de 2025
	Summary: Una introducción práctica a la arquitectura de sistemas modernos.
	Chapter: Introducción
		Content >>
			Conceptos básicos y objetivos del libro.
# ERROR: la fecha no es YYYY-MM-DD y falta ISBN, que es obligatorio

stxt validate docs/book.stxt

/home/ana/libros/docs/book.stxt:6: [INVALID_VALUE] Published: Invalid date (1 de octubre de 2025) (error)
/home/ana/libros/docs/book.stxt:1: [TOO_FEW_CHILDREN] 0 nodes of 'com.acme.book:isbn' and min is 1 (error)
2 error(s), 0 warning(s)

Cada hallazgo es fichero:línea: [CÓDIGO] mensaje (severidad). El código es estable y es el mismo en la CLI, en la extensión y en las tres bibliotecas (INVALID_VALUE, TOO_FEW_CHILDREN, CHILD_NOT_DECLARED, INDENTATION_MIXED…), de modo que sirve para buscar en la documentación o para filtrar en un script. La cardinalidad que falla se señala en la línea del padre (Book, línea 1), porque es el padre el que tiene cero ISBN.

El código de salida distingue los documentos tienen errores (1) de el comando se ha usado mal (2). Tres opciones cambian qué cuenta como fallo:

• --warn-schema: los errores de gramática se reportan como avisos y no hacen fallar; los de sintaxis, sí.
• --no-schema: solo sintaxis, sin buscar ni aplicar gramáticas.
• --format json: los mismos hallazgos como array JSON, para máquinas.

Con --recursive (-r) se validan directorios enteros; los .stxt/ encontrados por el camino se omiten, porque son la cadena de resolución, no documentos que comprobar.

4. Lo mismo desde VS Code

Con la carpeta libros/ abierta en Visual Studio Code y la extensión instalada (code --install-extension stxt-lang.stxt) no hay nada que configurar: la extensión sigue la misma cadena de resolución que la CLI —los .stxt/ del documento y de sus ancestros, aunque estén por encima de la raíz del workspace, y después ~/.stxt y /etc/stxt—, de modo que resuelve la misma plantilla y emite los mismos códigos. Con docs/book.stxt abierto:

• Los errores de sintaxis aparecen subrayados en rojo, y los de gramática como avisos, con el mismo código y mensaje que en la línea de comandos.
• Autocompletado (Ctrl+Espacio): dentro de Book propone solo los hijos que la plantilla permite; en un ENUM, sus valores.
• Hover sobre un nombre de nodo: su nombre canónico, su tipo, los valores permitidos si es un ENUM y la descripción que dé la plantilla.
• Ir a la definición (F12) sobre Published abre .stxt/@stxt.template/com.acme.book.stxt en la línea Published: (?) DATE.
• Formatear documento, desde la paleta de comandos o el atajo del editor: reindenta y normaliza sin perder comentarios ni líneas en blanco.

Al editar la plantilla, la extensión vuelve a resolver y revalida los documentos abiertos sin recargar nada. Si un documento tiene namespace pero no hay gramática en ninguna parte, no se muestra ningún aviso: los esquemas son opcionales, y un documento sin gramática no es incorrecto, solo no se puede validar.

5. Más de un nivel: usuario y sistema

El .stxt/ del proyecto es el primer nivel de la cadena; hay dos más:

La precedencia es por namespace, no por directorio: para cada namespace manda el nivel más cercano que lo defina, y los demás niveles siguen aportando los namespaces que ese no define. Así, un proyecto puede llevar su com.acme.book y el usuario tener en ~/.stxt una plantilla org.ana.notas para sus apuntes, y las dos aplican en la misma validación.

No se permiten dos definiciones del mismo namespace en el mismo nivel. Si la plantilla del libro se copia a .stxt/otro/copia.stxt, stxt schemas lo informa y el namespace queda sin definición activa hasta que se retire una de las dos:

stxt schemas docs

Resolution chain for /home/ana/libros/docs:
    /home/ana/libros/.stxt

No namespaces resolved.

Errors:
    DISCOVERY_DUPLICATE_NAMESPACE /home/ana/libros/.stxt/otro/copia.stxt: Duplicate definition for namespace 'com.acme.book' at level /home/ana/libros/.stxt: already defined in /home/ana/libros/.stxt/@stxt.template/com.acme.book.stxt

stxt validate reporta ese mismo error (línea 0, con el fichero causante) y falla: la herramienta nunca elige una de las dos en silencio. Ver STXT-DISCOVERY-SPEC §5 y §8.

6. Integración continua y STXT_PATH

En un trabajo de CI el resultado no debería depender del contenido de ~/.stxt o /etc/stxt en la máquina que lo ejecuta. La variable de entorno STXT_PATH sustituye la cadena de resolución entera por una lista de directorios (separados por :, o ; en Windows), en orden de precedencia; las entradas no tienen por qué llamarse .stxt. Con ella, dos pasos hacen fallar el trabajo si algún documento no valida o no está bien formateado:

STXT_PATH=./.stxt npx @stxt-lang/cli validate --recursive docs/
npx @stxt-lang/cli format --check --recursive docs/

format --check no escribe nada: solo lista qué ficheros cambiarían y falla si hay alguno, como gofmt -l o prettier --check. Reformatear requiere --write; ningún comando reescribe ficheros sin una petición explícita.

Una STXT_PATH definida pero vacía deja la cadena vacía: ningún documento con namespace encuentra gramática y validate falla con SCHEMA_NOT_FOUND; para comprobar solo la sintaxis hay que pedirlo explícitamente con --no-schema. Una entrada que no existe no aporta nada y no es un error. Ver STXT-DISCOVERY-SPEC §6.

7. Sin instalar nada: el playground

En el playground no hay sistema de ficheros, de modo que no hay .stxt/ ni cadena de directorios: la asociación entre documentos y gramáticas es por namespace dentro del workspace. Toda plantilla o esquema presente en la lista de documentos alimenta la validación, y cada documento se valida contra la definición cuyo namespace le corresponde. Dos gramáticas con el mismo namespace en el workspace son un error, exactamente como en la sección 5.

La semilla inicial incluye book.stxt y la gramática com.acme.book: al alterar la fecha o eliminar el ISBN del libro, el panel de problemas del pie muestra los mismos códigos que la CLI. El autocompletado, el hover y el interruptor de tabuladores/espacios funcionan igual que en la extensión, y Share copia una URL que contiene el workspace entero, para compartirlo sin instalación.

8. Resumen