Node.js · API
Lint
El módulo donly/lint valida un documento contra
un objeto de reglas y devuelve los problemas encontrados. Los ejemplos usan este
app.donly:
name "my-app"
port 8080
enabled true
server {
host "example.com"
route GET /home {
respond 200
}
route POST /api/user
} lint(text, rules)
Recibe el texto del documento y las reglas. Devuelve un arreglo de
LintIssue, vacío si todo es válido.
lint es también el nombre corto de
lintSchema.
import { lint, renderReport } from "donly/lint";
const rules = {
"/port": { "[1]": { type: "number", gte: 1, lte: 65535 } },
};
lint(text, rules); // [] (el documento cumple las reglas) type LintSeverity = "error" | "warning" | "info";
interface LintIssue {
message: string;
severity: LintSeverity;
trace?: string;
loc?: { start: Token; end: Token };
} Forma de las reglas
Cada clave es un camino de directiva (/server,
/server/route). Dentro, otras claves
/hijo bajan un nivel y las claves
[N] restringen el argumento en la posición
N (desde 1). También existe la forma fusionada
"/port[1]".
const rules = {
// posición del argumento: [N] (desde 1) o "/ruta[N]"
"/port": { "[1]": { type: "number", gte: 1, lte: 65535 } },
"/server": {
"/route[1]": { enum: ["GET", "POST"] },
"/host[1]": { type: "string", pattern: "^[a-z.]+$" },
},
"/enabled": { "[1]": { or: [{ type: "boolean" }, { type: "number" }] } },
"/name": { "[1]": { not: { enum: ["admin"] } } },
}; - type:
string,number,bigint,boolean,nulloheredoc. - number / bigint:
gte,gt,lte,lt. - string / heredoc:
pattern(expresión regular) yflags. - Cualquier tipo:
enum,or,and,not,message,severityyevaluation.
Ocurrencias
required, min
y max controlan cuántas veces aparece una directiva.
lint(text, { "/database": { required: true } });
// error: required directive is missing
lint(text, { "/server": { "/route": { max: 1 } } });
// error: too many occurrences (max 1)
lint(text, { "/server": { "/route": { min: 3 } } });
// error: too few occurrences (min 3) Mensaje y severidad
message reemplaza el texto del problema y
severity lo cambia a "error",
"warning" o "info".
lint(text, {
"/database": {
required: true,
message: "falta database",
severity: "warning",
},
});
// [ { severity: 'warning', message: 'falta database' } ] Lógica propia
evaluation es una vía de escape: recibe la directiva
(o el argumento y su posición) y devuelve los problemas que quieras reportar.
lint(text, {
"/name": {
evaluation: (directive) => [
{ message: "revisado: " + directive.args[0], severity: "info" },
],
},
});
// [ { severity: 'info', message: 'revisado: my-app' } ] Reglas en un archivo .donly
Las reglas también pueden escribirse en sintaxis DON.
parseLintRulesDonly las convierte en el mismo
objeto de reglas.
/port {
[1] {
type "string"
}
} import { lint, parseLintRulesDonly } from "donly/lint";
const rules = parseLintRulesDonly(`
/port {
[1] {
type "number"
gte 1
lte 1000
}
}
`);
JSON.stringify(rules);
// {"/port":{"[1]":{"type":"number","gte":1,"lte":1000}}} format
format refina un type, como el
format de JSON Schema: el argumento debe cumplir el
type y el formato. Los de fecha y hora se validan con
temporal-polyfill. Los nombres de fecha aceptan también su
alias en PascalCase (por ejemplo PlainDate). Un
format desconocido nunca coincide.
const rules = {
"/job/day": { "[1]": { type: "string", format: "plain-date" } },
"/job/createdAt": { "[1]": { type: "number", format: "unix" } },
"/server/port": { "[1]": { type: "number", format: "port", gte: 1024 } },
}; | format (type string) | Acepta |
|---|---|
| duration | ISO 8601 duration: P1Y2M3DT4H5M6.5S, PT30M |
| plain-date | YYYY-MM-DD |
| plain-time | HH:mm, HH:mm:ss, HH:mm:ss.fffffffff |
| plain-date-time | YYYY-MM-DDTHH:mm[:ss[.f]], sin Z ni offset |
| instant | fecha y hora con Z u offset obligatorio |
| plain-year-month | YYYY-MM |
| plain-month-day | MM-DD o --MM-DD |
| zoned-date-time | fecha y hora con [zona IANA] obligatoria |
| json | texto que parsea como JSON (también con type heredoc, sobre su contenido) |
| url | URL absoluta |
| ipv4 | IPv4 con rango CIDR /0 a /32 opcional |
| ipv6 | IPv6 con rango /0 a /128 opcional |
| CIDR | IPv4 o IPv6, cada una con su rango opcional |
| hostname | RFC 1123 |
| uuid | UUID canónico, cualquier caso (versiones 1 a 8, nil y max) |
| RFC 5322 addr-spec | |
| regexp | un string que compila con new RegExp |
| semver | Semantic Versioning 2.0.0, sin v inicial |
| format (type number o bigint) | Acepta |
|---|---|
| port | entero de 0 a 65535 |
| port-well-known | 0 a 1023 |
| port-registered | 1024 a 49151 |
| port-ephemeral | 49152 a 65535 |
| epoch-seconds (alias unix) | segundos desde la época Unix |
| epoch-milliseconds | milisegundos desde la época Unix |
| epoch-nanoseconds (type bigint) | nanosegundos desde la época Unix, por ejemplo 1709202600000000000n |
gte, gt, lte y
lt siguen aplicando junto a un formato numérico; por ejemplo,
{ type: "number", format: "port", gte: 1024 } prohíbe los puertos
privilegiados. En .donly se escribe como una propiedad más: format "plain-date".
Mensajes por defecto
Todo problema tiene message, severidad
"error" por defecto y, si se puede ubicar, loc. Un message propio en la regla reemplaza al mensaje por defecto, que nunca repite el valor
ofensivo (podría ser un secreto). N
es la posición del argumento, desde 1.
| Caso | Mensaje por defecto |
|---|---|
| Un argumento falla su restricción y tiene type | argument at position N must be of type T |
| Falla la restricción y no hay type (enum, pattern, rango, or/and/not) | argument at position N does not satisfy the constraint |
| Tiene el type correcto pero falla su format | argument at position N must be a valid F: … |
| El format no existe | argument at position N has an unknown format "F" |
| Una subruta aparece más de max veces | too many occurrences (max M) |
| Una subruta aparece menos de min veces | too few occurrences (min M) |
| Falta una subruta required | required directive is missing |
| Un not de documento cuya regla coincide | document must not match the given rule |
Cuando falla un format, el mensaje nombra el
formato tal como lo escribió la regla, lo describe y da un ejemplo. Los
formatos IP mencionan el rango solo si el valor se escribió con uno.
argument at position 1 must be a valid ipv4: an IPv4 address (e.g. 192.0.2.1)
argument at position 1 must be a valid ipv4: an IPv4 address with a range from /0 to /32 (e.g. 10.0.0.0/8) Raíz, comodín y expresiones de ruta
-
"/"es la raíz del documento y"/*"cualquier directiva hija; conmaxomin,"/*"cuenta todas las hijas de cualquier nombre. -
Las claves reutilizan las expresiones de ruta:
"/route(GET)","/route(* text-*)". -
or,andynottambién valen a nivel de documento. -
requiredpuede depender de una subruta, por ejemplo exigir/respondsolo cuando existe/route.
const rules = {
// "/" es la raíz del documento; "/*" cuenta cualquier directiva hija
"/*": { max: 1, message: "solo una directiva en la raíz" },
// la clave puede usar expresiones de ruta: argumentos exactos o patrones
"/route(GET)": { "/respond": { max: 1 } },
"/route(* text-*)": { "[1]": { type: "string" } },
};
// or / and / not también valen en la raíz del documento
const either = {
or: [
{ "/server/port": { required: true } },
{ "/server/socket": { required: true } },
],
}; Reglas en .donly: la correspondencia
La conversión de un archivo de reglas .donly es estructural: cada
directiva es una entrada del objeto, con su nombre como clave.
-
Sin argumentos ni hijos es un booleano:
requiredequivale atrue. -
Con argumentos y sin hijos es un valor (
max 1es1) o, con varios argumentos, un arreglo (enum "a" "b"). -
Con hijos es un objeto. Un string inicial junto a los hijos es atajo de
message. -
Escribe
"/*"entre comillas: sin ellas choca con el comentario de bloque/* */. -
Dentro de
or/and, un hijo llamado/es una etiqueta de agrupación que se descarta. evaluationno tiene forma en .donly: solo en código.
or {
/server/port { required }
/server/socket { required }
}
/server/route {
/respond "respond es obligatorio dentro de un route" {
min 1
}
}
"/*" { max 1 } Reportes
renderReport(issues, { filePath, asciiColor? })
produce un texto legible, con línea y columna desde 1. Con
asciiColor agrega colores ANSI.
renderJSONReport devuelve el mismo reporte en
JSON; line y column son null si el problema
no tiene ubicación (por ejemplo, una directiva requerida que falta).
import { renderJSONReport } from "donly/lint";
renderJSONReport(issues, { filePath: "app.donly" });
// {
// "filePath": "app.donly",
// "issues": [
// { "line": 2, "column": 6, "severity": "error",
// "message": "argument at position 1 must be of type string" }
// ],
// "summary": { "errors": 1, "warnings": 0, "info": 0 }
// } CLI
npx donly lint usa esta misma API. Acepta reglas
en .json o .donly, y termina con código 1 si hay
errores. Más opciones en la página de la CLI.
$ npx donly lint --rules rules.donly app.donly
app.donly
2:6 error argument at position 1 must be of type string
1 error 0 warnings 0 info
$ npx donly lint --rules rules.donly -o json app.donly # salida JSON