Generador de documentación: de JSDoc a Markdown, con avisos

1const fuente = require("fs").readFileSync(0, "utf8");
2
3const ETIQUETAS = ["param", "returns", "return", "throws", "example", "deprecated", "private", "since"];
4
5// Funciones de primer nivel (empiezan en la columna 0): declaradas o asignadas a una constante
6const RE_FUNCION = /^(?:export\s+)?(?:async\s+)?function\s*([A-Za-z_$][\w$]*)\s*\(([^)]*)\)/gm;
7const RE_CONSTANTE = /^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?(?:function\s*\(([^)]*)\)|\(([^)]*)\)\s*=>|([A-Za-z_$][\w$]*)\s*=>)/gm;
8
9/** Todas las funciones, en el orden del código: { nombre, params, inicio, fin, flecha }. */
10function buscarFunciones() {
11  const r = [];
12  for (const m of fuente.matchAll(RE_FUNCION)) r.push({ nombre: m[1], params: m[2], inicio: m.index, fin: m.index + m[0].length, flecha: false });
13  for (const m of fuente.matchAll(RE_CONSTANTE)) {
14    r.push({ nombre: m[1], params: m[2] ?? m[3] ?? m[4], inicio: m.index, fin: m.index + m[0].length, flecha: m[2] === undefined });
15  }
16  return r.sort((a, b) => a.inicio - b.inicio);
17}
18
19/** "a, b = 2, ...resto" → ["a", "b", "...resto"] */
20const nombresParametros = (texto) => texto.split(",").map((p) => p.split("=")[0].trim()).filter(Boolean);
21
22/** El cuerpo entre llaves que empieza en la primera { desde la posición dada (sin contar las llaves de los textos). */
23function cuerpo(desde) {
24  const inicio = fuente.indexOf("{", desde);
25  if (inicio < 0) return "";
26  let nivel = 0, comilla = null;
27  for (let i = inicio; i < fuente.length; i++) {
28    const c = fuente[i];
29    if (comilla) {
30      if (c === "\\") i++;
31      else if (c === comilla) comilla = null;
32    } else if (c === '"' || c === "'" || c === "`") comilla = c;
33    else if (c === "{") nivel++;
34    else if (c === "}" && --nivel === 0) return fuente.slice(inicio, i + 1);
35  }
36  return fuente.slice(inicio);
37}
38
39/** ¿Devuelve un valor? Una flecha sin llaves devuelve su expresión; si no, hace falta un return con algo. */
40function devuelveValor(f) {
41  if (f.flecha && !/^\s*\{/.test(fuente.slice(f.fin))) return true;
42  return /\breturn\s*[^;\s}]/.test(cuerpo(f.fin));
43}
44
45/** El comentario /** ... *\/ pegado justo antes de la posición, o null. */
46function jsdocAntes(posicion) {
47  const antes = fuente.slice(0, posicion).trimEnd();
48  if (!antes.endsWith("*/")) return null;
49  const inicio = antes.lastIndexOf("/**");
50  // si después del /** empieza otro comentario normal, el que va pegado no es JSDoc
51  if (inicio < 0 || antes.lastIndexOf("/*") !== inicio) return null;
52  return antes.slice(inicio + 3, -2);
53}
54
55/** Descripción y etiquetas: [{ nombre, texto }]; el texto de @example conserva los saltos de línea. */
56function analizar(comentario) {
57  let filas = comentario.split("\n").map((l) => l.replace(/^\s*\* ?/, "").trimEnd());
58  // en un comentario de una línea las etiquetas van seguidas: /** Texto. @returns {string} */
59  if (filas.length === 1) filas = filas[0].split(/\s+(?=@[a-z]+\b)/);
60  const descripcion = [], etiquetas = [];
61  for (const fila of filas) {
62    const m = /^@(\w+)\s?(.*)$/.exec(fila.trim());
63    if (m) etiquetas.push({ nombre: m[1], filas: [m[2]] });
64    else if (etiquetas.length) etiquetas[etiquetas.length - 1].filas.push(fila);
65    else descripcion.push(fila.trim());
66  }
67  return {
68    descripcion: descripcion.filter(Boolean).join(" "),
69    etiquetas: etiquetas.map((e) => ({
70      nombre: e.nombre,
71      texto: e.nombre === "example" ? e.filas.join("\n").replace(/^\n+|\n+$/g, "") : e.filas.map((f) => f.trim()).filter(Boolean).join(" "),
72    })),
73  };
74}
75
76const celda = (s) => s.replace(/\|/g, "\\|");
77
78function documentar(f, doc, avisos) {
79  const params = nombresParametros(f.params);
80  const limpios = params.map((p) => p.replace(/^\.\.\./, ""));
81  const md = ["", `## \`${f.nombre}(${params.join(", ")})\``, ""];
82  const etiqueta = (n) => doc.etiquetas.filter((e) => e.nombre === n);
83  const obsoleta = etiqueta("deprecated")[0];
84  if (obsoleta) md.push(obsoleta.texto ? `> **Obsoleta:** ${obsoleta.texto}` : "> **Obsoleta.**", "");
85  if (doc.descripcion) md.push(doc.descripcion, "");
86  const desde = etiqueta("since")[0];
87  if (desde) md.push(`*Desde la versión ${desde.texto}.*`, "");
88
89  const documentados = {};
90  for (const e of etiqueta("param")) {
91    const m = /^\{([^}]+)\}\s+(\[[^\]]+\]|[\w$.]+)\s*(?:-\s*)?(.*)$/.exec(e.texto);
92    if (!m) {
93      avisos.push(`${f.nombre}: @param mal escrito «${e.texto}»`);
94      continue;
95    }
96    let nombre = m[2], extra = "";
97    if (nombre.startsWith("[")) {
98      const [n, defecto] = nombre.slice(1, -1).split("=");
99      nombre = n.trim();
100      extra = defecto === undefined ? " *(opcional)*" : ` *(opcional, por defecto \`${defecto.trim()}\`)*`;
101    }
102    if (!limpios.includes(nombre)) avisos.push(`${f.nombre}: @param «${nombre}» no existe en la función`);
103    else documentados[nombre] = { tipo: m[1], texto: m[3] + extra };
104  }
105  if (limpios.length) {
106    md.push("**Parámetros**", "", "| Nombre | Tipo | Descripción |", "| --- | --- | --- |");
107    for (const p of limpios) {
108      const d = documentados[p];
109      if (!d) avisos.push(`${f.nombre}: el parámetro «${p}» no está documentado`);
110      md.push(d ? `| \`${p}\` | \`${celda(d.tipo)}\` | ${celda(d.texto.trim())} |` : `| \`${p}\` | — | *sin documentar* |`);
111    }
112    md.push("");
113  }
114
115  const devuelve = [...etiqueta("returns"), ...etiqueta("return")][0];
116  const valor = devuelveValor(f);
117  if (devuelve) {
118    const m = /^(?:\{([^}]+)\})?\s*(?:-\s*)?(.*)$/.exec(devuelve.texto);
119    md.push(`**Devuelve**${m[1] ? ` \`${m[1]}\`` : ""}${m[2] ? `: ${m[2]}` : ""}`, "");
120    if (!valor && !/^(void|undefined)$/.test(m[1] ?? "")) avisos.push(`${f.nombre}: tiene @returns pero no devuelve nada`);
121  } else if (valor) {
122    avisos.push(`${f.nombre}: devuelve un valor pero falta @returns`);
123  }
124  for (const e of etiqueta("throws")) {
125    const m = /^(?:\{([^}]+)\})?\s*(?:-\s*)?(.*)$/.exec(e.texto);
126    md.push(`**Lanza**${m[1] ? ` \`${m[1]}\`` : ""}${m[2] ? `: ${m[2]}` : ""}`, "");
127  }
128  for (const e of etiqueta("example")) md.push("**Ejemplo**", "", "```js", e.texto, "```", "");
129  for (const e of doc.etiquetas) {
130    if (!ETIQUETAS.includes(e.nombre)) avisos.push(`${f.nombre}: etiqueta desconocida @${e.nombre}`);
131  }
132  while (md[md.length - 1] === "") md.pop();
133  return md;
134}
135
136function main() {
137  const salida = ["# Documentación"];
138  const avisos = [];
139  for (const f of buscarFunciones()) {
140    const comentario = jsdocAntes(f.inicio);
141    const doc = comentario === null ? null : analizar(comentario);
142    if (f.nombre.startsWith("_") || doc?.etiquetas.some((e) => e.nombre === "private")) continue;
143    if (!doc) {
144      avisos.push(`${f.nombre}: sin documentar`);
145      continue;
146    }
147    salida.push(...documentar(f, doc, avisos));
148  }
149  salida.push("", "## Avisos", "");
150  if (avisos.length === 0) salida.push("Ninguno.");
151  for (const a of avisos) salida.push(`- ${a}`);
152  console.log(salida.join("\n"));
153}
154
155main();