Scripts de apoyo como software reusable

El contrato operativo de un script describe cómo se ejecuta, qué entradas acepta, qué salida produce, cómo informa fallas y qué condiciones del entorno necesita.

Este fragmento introduce una idea de diseño y varias piezas pequeñas de sintaxis. La idea de diseño es simple: cuando varios valores representan una misma categoría, conviene agruparlos y darles un nombre.

• valval declara una referencia que no puede reasignarse. Después de definir expectedFilesexpectedFiles, ese nombre no puede apuntar a otra lista dentro del mismo alcance.
• Esa inmutabilidad corresponde a la referencia, no necesariamente a una inmutabilidad profunda de todo lo que podría estar contenido en un objeto. En este caso, listOf()listOf() crea una lista de solo lectura, adecuada para expresar que el criterio del script no cambia durante esta ejecución.
• Kotlin también ofrece mutableListOf()mutableListOf() para crear listas modificables. No la usamos aquí porque no queremos agregar ni quitar archivos esperados mientras el script corre: queremos declarar el criterio inicial y mantenerlo estable.
• System.lineSeparator()System.lineSeparator() obtiene el salto de línea recomendado por el sistema operativo. Luego, el operador ++ concatena ese salto de línea con "- ""- " para formar el separador que aparecerá antes de cada archivo.
• El símbolo $$ permite interpolar valores dentro de un texto. Por eso "Expected files:$separator""Expected files:$separator" inserta el contenido de separatorseparator después del título.
• joinToString()joinToString() construye un texto a partir de los elementos de una colección. En este caso, usa separatorseparator entre cada archivo y prefixprefix antes del primer elemento.

Este fragmento introduce dos ideas importantes para scripts de apoyo: leer argumentos de la terminal y validar una precondición antes de usar esos argumentos.

• argsargs contiene los argumentos recibidos al ejecutar el script. Por ejemplo, si ejecutamos kotlin check-library-layout.main.kts ., el punto . queda disponible como el primer argumento.
• args[0]args[0] obtiene el primer argumento. En este caso lo guardamos en projectPathprojectPath porque representa la ruta del proyecto que queremos revisar.
• require(args.isNotEmpty())require(args.isNotEmpty()) valida que exista al menos un argumento. Si la condición es verdadera, el script continúa. Si es falsa, Kotlin detiene la ejecución con un error que incluye el mensaje indicado.
• El bloque { "Missing required argument: <project-path>" }{ "Missing required argument: <project-path>" } es una lambda: una función pequeña escrita directamente donde se necesita. Aquí se usa para producir el mensaje de error solo si la validación falla.
• Esta forma de escribir la lambda después de los paréntesis se llama trailing lambda. En Kotlin, cuando el último argumento de una función es otra función, esa lambda puede escribirse fuera de los paréntesis. Es la misma idea de pasar una función como argumento, pero con una sintaxis más legible.

La línea con require()require() evita que el script intente leer args[0]args[0] cuando no se entregó ningún argumento. Esa es una regla pequeña, pero muy importante para scripts reutilizables: primero se comprueba el contrato de entrada, después se trabaja con los datos.

Este fragmento combina tres ideas: declarar una función, representar rutas del sistema de archivos y repetir una acción para cada elemento de una lista.

• funfun declara una función. En este caso, checkPath()checkPath() recibe dos parámetros: la ruta base del proyecto y una ruta relativa que queremos revisar.
• Los parámetros se escriben con la forma nombre: Tiponombre: Tipo. Por eso projectDirectory: PathprojectDirectory: Path indica que projectDirectoryprojectDirectory debe ser una ruta, mientras que relativePath: StringrelativePath: String indica que relativePathrelativePath es texto.
• PathPath representa una ruta del sistema de archivos. En el fragmento, Path.of(projectPath)Path.of(projectPath) convierte el texto recibido por argumento en una ruta que el script puede usar para construir otras rutas.
• projectDirectory.resolve(relativePath)projectDirectory.resolve(relativePath) construye una ruta dentro del directorio del proyecto. Por ejemplo, si el proyecto es . y la ruta relativa es README.md, el script revisará el archivo ./README.md.
• Files.exists(path)Files.exists(path) pregunta si esa ruta existe. El resultado se usa en un ifif para imprimir Found cuando la ruta está presente o Missing cuando no lo está.
• for (expectedFile in expectedFiles)for (expectedFile in expectedFiles) repite una acción por cada elemento de la lista expectedFilesexpectedFiles. En cada vuelta, el valor actual queda disponible con el nombre expectedFileexpectedFile.
• La llamada checkPath(projectDirectory, expectedFile)checkPath(projectDirectory, expectedFile) reutiliza la misma función para cada archivo esperado. Así evitamos escribir varias veces la misma estructura de ifif.

checkPath()checkPath() no se extrae porque el script sea grande, sino porque la operación tiene una responsabilidad clara: recibir una ruta base, combinarla con una ruta relativa y comunicar si existe. Esa separación hace que el script sea más fácil de leer y cambiar.