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"] } } },
};

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
durationISO 8601 duration: P1Y2M3DT4H5M6.5S, PT30M
plain-dateYYYY-MM-DD
plain-timeHH:mm, HH:mm:ss, HH:mm:ss.fffffffff
plain-date-timeYYYY-MM-DDTHH:mm[:ss[.f]], sin Z ni offset
instantfecha y hora con Z u offset obligatorio
plain-year-monthYYYY-MM
plain-month-dayMM-DD o --MM-DD
zoned-date-timefecha y hora con [zona IANA] obligatoria
jsontexto que parsea como JSON (también con type heredoc, sobre su contenido)
urlURL absoluta
ipv4IPv4 con rango CIDR /0 a /32 opcional
ipv6IPv6 con rango /0 a /128 opcional
CIDRIPv4 o IPv6, cada una con su rango opcional
hostnameRFC 1123
uuidUUID canónico, cualquier caso (versiones 1 a 8, nil y max)
emailRFC 5322 addr-spec
regexpun string que compila con new RegExp
semverSemantic Versioning 2.0.0, sin v inicial
format (type number o bigint)Acepta
portentero de 0 a 65535
port-well-known0 a 1023
port-registered1024 a 49151
port-ephemeral49152 a 65535
epoch-seconds (alias unix)segundos desde la época Unix
epoch-millisecondsmilisegundos 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.

CasoMensaje por defecto
Un argumento falla su restricción y tiene typeargument 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 formatargument at position N must be a valid F: …
El format no existeargument at position N has an unknown format "F"
Una subruta aparece más de max vecestoo many occurrences (max M)
Una subruta aparece menos de min vecestoo few occurrences (min M)
Falta una subruta requiredrequired directive is missing
Un not de documento cuya regla coincidedocument 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

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.

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