@ingenioz-it/caits 0.5.1 → 0.7.0

package/bin/caits.js

@@ -3,6 +3,7 @@
 import { existsSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
+import { commandOf, painterOf } from "../quality/terminal.mjs";
 import { defaultsVersions, DEFAULTS_FOLDER, EXAMPLE_SOURCE, init, install, otherVersions, SOURCE, update, VERSION } from "./init.js";
 
 const USAGE = `Usage: caits <command>
@@ -24,8 +25,8 @@ const USAGE = `Usage: caits <command>
   architecture         Checks the rules of quality/architecture.mjs.
   e2e                  Runs the end-to-end tests on the production build.
   mutation             Runs the mutation tests (Stryker), then gives the score of each file and the mutants that survived. Its exit
-                       code is that of Stryker.
-  mutation-summary     Gives the mutation score of each file (--survivors: the mutants that survived).
+                       code is that of Stryker, or 1 when a mutant was not tested (its unit tests did not run).
+  mutation-summary     Gives the mutation score of each file (--survivors: the mutants that survived, and those not tested).
   mutation-suite       The unit tests, as Stryker runs them for each mutant.
 
   --help, -h           Shows this help, also after a command (caits init --help).
@@ -46,6 +47,10 @@ const count = (count, noun) => `${count} ${noun}${count === 1 ? "" : "s"}`;
 /** A folder as the shell reads it: in quotes when it has a space or another special character. */
 const shellQuote = (/** @type {string} */ text) => /^[\w@%+=:,./-]+$/.test(text) ? text : `'${text.replaceAll("'", "'\\''")}'`;
 
+/** The painters of the output and of the errors: they color in a terminal only. */
+const paint = painterOf(process.stdout);
+const paintError = painterOf(process.stderr);
+
 const [command, ...rest] = process.argv.slice(2);
 
 try {
@@ -53,8 +58,8 @@ try {
   if (typeof status === "number") process.exitCode = status;
 } catch (error) {
   // A known problem has a message that tells what to do: the stack of the code of CAITS does not help.
-  console.error(error instanceof Error ? error.message : error);
-  if (error instanceof UsageError) console.error("Run `caits --help`.");
+  console.error(paintError("red", String(error instanceof Error ? error.message : error)));
+  if (error instanceof UsageError) console.error(paintError("dim", "Run `caits --help`."));
   process.exitCode = 1;
 }
 
@@ -125,7 +130,7 @@ function runInit(args) {
   const options = /** @type {{ caits?: string; example?: boolean; "example-source"?: string; "no-install"?: boolean }} */ (values);
   if (positionals.length > 1) throw new UsageError(`init takes one folder, not ${positionals.length}: ${positionals.join(" ")}.`);
   if (positionals.length === 0 && !existsSync("package.json")) {
-    console.error("This folder has no package.json. Give the folder of the new project (`caits init my-app`), or `caits init .` to use this folder.");
+    console.error(paintError("red", "This folder has no package.json. Give the folder of the new project (`caits init my-app`), or `caits init .` to use this folder."));
     return 1;
   }
   const root = resolve(positionals[0] ?? ".");
@@ -134,7 +139,7 @@ function runInit(args) {
   console.log(`CAITS ${VERSION}: ${root}\n`);
   if (example) console.log(`The example: ${example}\n`);
   const { written, kept, ignored, values: keptValues } = init(root, options.caits, { example });
-  console.log(`Wrote ${count(written.length, "file")}. CAITS owns those of ${DEFAULTS_FOLDER}/: the others are yours.`);
+  console.log(paint("green", `Wrote ${count(written.length, "file")}. CAITS owns those of ${DEFAULTS_FOLDER}/: the others are yours.`));
   if (kept.length > 0) {
     console.log(`Kept ${count(kept.length, "file")} that the project has already: ${kept.join(", ")}.`);
     console.log("  Compare them with those of node_modules/@ingenioz-it/caits/template/project/ (without the dot at the start of the name).");
@@ -148,11 +153,11 @@ function runInit(args) {
   const cd = relative(process.cwd(), root);
   const steps = [...(cd ? [`cd ${shellQuote(cd)}`] : []), ...(withInstall ? [] : ["npm install", "npx playwright install chromium"])];
   if (withInstall && !install(root)) {
-    console.error("\nThe installation failed. Correct the problem, then run the same command again: it keeps the files that it wrote.");
+    console.error(`\n${paintError("red", "The installation failed. Correct the problem, then run the same command again: it keeps the files that it wrote.")}`);
     return 1;
   }
-  console.log("\nNext:");
-  for (const step of [...steps, "npm run dev      starts the app on http://localhost:3000", "npm run check    runs all the checks"]) console.log(`  ${step}`);
+  console.log(`\n${paint("bold", "Next:")}`);
+  for (const step of [...steps, "npm run dev      starts the app on http://localhost:3000", "npm run check    runs all the checks"]) console.log(`  ${commandOf(step, paint)}`);
   return 0;
 }
 
@@ -164,7 +169,7 @@ function runInit(args) {
 function runUpdate(args) {
   if (args.length > 0) throw new UsageError(`update takes no argument: ${args.join(" ")}.`);
   const written = update(process.cwd());
-  console.log(`CAITS ${VERSION}: wrote ${count(written.length, "file")} in ${DEFAULTS_FOLDER}/.`);
+  console.log(paint("green", `CAITS ${VERSION}: wrote ${count(written.length, "file")} in ${DEFAULTS_FOLDER}/.`));
   printOtherVersions(process.cwd());
   return 0;
 }
@@ -173,7 +178,7 @@ function runUpdate(args) {
 function printOtherVersions(root) {
   const others = otherVersions(root);
   if (others.length === 0) return;
-  console.log(`CAITS ${VERSION} suggests other versions of these packages. Change them in package.json if you agree:`);
+  console.log(paint("yellow", `CAITS ${VERSION} suggests other versions of these packages. Change them in package.json if you agree:`));
   for (const { key, project, caits } of others) console.log(`  ${key}: ${JSON.stringify(project)} (CAITS suggests ${JSON.stringify(caits)})`);
 }
 
@@ -182,5 +187,5 @@ function warnOfOldDefaults(root) {
   const versions = defaultsVersions(root);
   if (versions.length === 1 && versions[0] === VERSION) return;
   const from = versions.length === 0 ? "is missing" : `comes from CAITS ${versions.join(", ")}`;
-  console.warn(`Warning: ${DEFAULTS_FOLDER}/ ${from}, but CAITS ${VERSION} is installed. Run \`npx caits update\`.\n`);
+  console.warn(`${paintError("yellow", "Warning:")} ${DEFAULTS_FOLDER}/ ${from}, but CAITS ${VERSION} is installed. Run \`npx caits update\`.\n`);
 }

package/bin/init.js

@@ -4,6 +4,7 @@ import { appendFileSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readd
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { painterOf } from "../quality/terminal.mjs";
 
 /** @typedef {{ [key: string]: unknown }} PackageJson */
 /** @typedef {{ [name: string]: string }} Section */
@@ -209,12 +210,20 @@ function cloneExample(source) {
  */
 export function update(root) {
   const folder = join(root, DEFAULTS_FOLDER);
-  rmSync(folder, { recursive: true, force: true });
+  const defaults = new Map(filesOf(DEFAULTS).map(file => [file, headerOf(VERSION) + readFileSync(join(DEFAULTS, file), "utf8")]));
   mkdirSync(folder, { recursive: true });
-  return filesOf(DEFAULTS).map(file => {
-    writeFileSync(join(folder, file), headerOf(VERSION) + readFileSync(join(DEFAULTS, file), "utf8"));
-    return `${DEFAULTS_FOLDER}/${file}`;
-  });
+  for (const entry of readdirSync(folder, { recursive: true, withFileTypes: true })) {
+    const file = relative(folder, join(entry.parentPath, entry.name)).split(sep).join("/");
+    if (!entry.isDirectory() && !(entry.isFile() && defaults.has(file))) rmSync(join(folder, file), { force: true });
+  }
+  // Only the files that change are written: a development server that watches the others (vite.ts, tsconfig.json) does not restart.
+  for (const [file, text] of defaults) {
+    const path = join(folder, file);
+    if (existsSync(path) && readFileSync(path, "utf8") === text) continue;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+  }
+  return [...defaults.keys()].map(file => `${DEFAULTS_FOLDER}/${file}`);
 }
 
 /**
@@ -261,7 +270,7 @@ export function install(root) {
 function run(command, args, cwd) {
   console.log(`\n> ${[command, ...args].join(" ")}`);
   const result = spawnSync(command, args, { cwd, stdio: "inherit" });
-  if (result.error) console.error(`${notStarted(command, result.error)}.`);
+  if (result.error) console.error(painterOf(process.stderr)("red", `${notStarted(command, result.error)}.`));
   return result.status === 0;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingenioz-it/caits",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "CAITS (Clean Architecture In TypeScript): the technical base of a Marko project with a backend and a frontend.",
   "keywords": [
     "clean-architecture",

package/quality/architecture/adapters/marko.mjs

@@ -5,19 +5,22 @@ import { factsOf } from "../facts.mjs";
 /**
  * Reads a Marko template (its absolute path, and its text) with the Marko compiler: it parses the markup and the JavaScript in it,
  * and translates nothing.
- * A tag that Marko finds by discovery (in a tags/ folder of the project) is a dependency without an import: it counts as one.
+ * A tag that Marko finds by discovery (in a tags/ folder, or in the folder of tags that a marko.json gives: the components of the
+ * frontend context shared) is a dependency without an import: it counts as one, from the root of the project (/src/…). The rules on
+ * the direction of the imports read it, at the line of its first tag; the rule on ../ does not, since nobody wrote it.
  * @param {string} file
  * @param {string} text
+ * @param {string} root the root of the project
  */
-export function readMarko(file, text) {
+export function readMarko(file, text, root) {
   const { ast } = compiler.compileSync(text, file, { output: "source", ast: true, code: false, sourceMaps: false });
   const facts = factsOf(ast.program, text);
   const lookup = compiler.taglib.buildLookup(dirname(file));
   for (const name of new Set(facts.tags)) {
     const template = lookup.getTag(name)?.template;
     if (!template || template === file || template.includes("/node_modules/")) continue;
-    const specifier = relative(dirname(file), template).replaceAll("\\", "/");
-    facts.imports.push(specifier.startsWith(".") ? specifier : `./${specifier}`);
+    facts.imports.push(`/${relative(root, template).replaceAll("\\", "/")}`);
+    facts.lines.imports.push(facts.lines.tags[facts.tags.indexOf(name)]);
   }
   return facts;
 }

package/quality/architecture/adapters/scss.mjs

@@ -1,4 +1,5 @@
 import { dirname, posix } from "node:path";
+import { linesIn } from "../facts.mjs";
 
 /** A string, or a comment: the comments are removed, the strings stay (a string can hold "//", as a URL does). */
 const STRING_OR_COMMENT = /("(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*')|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g;
@@ -10,7 +11,8 @@ const QUOTED = /^\s*(["'])(.+)\1\s*$/;
 export const STYLE_FOLDER = "src/routes/_frontend/style";
 
 /**
- * Reads a stylesheet (SCSS): the files that it loads with `@use`, `@forward` and `@import`. The comments do not count.
+ * Reads a stylesheet (SCSS): the files that it loads with `@use`, `@forward` and `@import`, in the order of their lines, and its comments.
+ * The comments load nothing.
  * Sass looks for a path first next to the file, then in its load path, then in the packages. Thus a path that leads to a file next to
  * the stylesheet (`theme` for _theme.scss) becomes relative (`./theme`); a path that leads to a file of the load path becomes a path
  * from the root of the project (`/src/routes/_frontend/style/values`); the others stay names of packages, as `sass:math` does.
@@ -19,19 +21,38 @@ export const STYLE_FOLDER = "src/routes/_frontend/style";
  * @param {Set<string>} paths the paths of all the files of the project
  */
 export function readScss(path, text, paths) {
-  const code = text.replace(STRING_OR_COMMENT, (/** @type {string} */ _match, /** @type {string | undefined} */ string) => string ?? "");
-  const specifiers = [...code.matchAll(USE_OR_FORWARD)].map(match => match[2]);
-  for (const [, list] of code.matchAll(IMPORT)) {
-    for (const item of list.split(",")) {
+  const lineAt = linesIn(text);
+  /** @type {string[]} */
+  const comments = [];
+  /** @type {number[]} */
+  const commentLines = [];
+  // A comment becomes the line breaks that it holds: the code keeps the lines of the text.
+  const code = text.replace(STRING_OR_COMMENT, (/** @type {string} */ match, /** @type {string | undefined} */ string, /** @type {number} */ offset) => {
+    if (string !== undefined) return string;
+    comments.push(match.startsWith("//") ? match.slice(2) : match.slice(2, -2));
+    commentLines.push(lineAt(offset));
+    return match.replace(/[^\n]/g, "");
+  });
+  const codeLineAt = linesIn(code);
+  /** @type {{ specifier: string; line: number }[]} */
+  const found = [...code.matchAll(USE_OR_FORWARD)].map(match => ({ specifier: match[2], line: codeLineAt(match.index ?? 0) }));
+  for (const match of code.matchAll(IMPORT)) {
+    let offset = (match.index ?? 0) + match[0].indexOf(match[1]);
+    for (const item of match[1].split(",")) {
       const [, , specifier] = QUOTED.exec(item) ?? [];
-      if (specifier) specifiers.push(specifier);
+      if (specifier) found.push({ specifier, line: codeLineAt(offset + item.indexOf(specifier)) });
+      offset += item.length + 1;
     }
   }
-  const imports = specifiers.map(specifier => {
+  found.sort((first, second) => first.line - second.line);
+  const imports = found.map(({ specifier }) => {
     if (isIn(dirname(path), specifier, paths)) return `./${specifier}`;
     return isIn(STYLE_FOLDER, specifier, paths) ? `/${posix.join(STYLE_FOLDER, specifier)}` : specifier;
   });
-  return { imports, exports: [], defaultArray: null, classes: [], constructed: [], calls: [], objectTypes: [], strings: [], tags: [] };
+  return {
+    imports, imported: [], exports: [], defaultArray: null, classes: [], constructed: [], calls: [], objectTypes: [], strings: [], tags: [], comments,
+    lines: { imports: found.map(({ line }) => line), constructed: [], objectTypes: [], tags: [], comments: commentLines }
+  };
 }
 
 /**

package/quality/architecture/adapters/typescript.mjs

@@ -7,7 +7,7 @@ import { factsOf } from "../facts.mjs";
  * @param {string} text
  */
 export function readTypeScript(path, text) {
-  const { program, errors } = parseSync(path, text);
+  const { program, errors, comments } = parseSync(path, text);
   if (errors.length > 0) throw new Error(`${path}: ${errors[0].message}`);
-  return factsOf(program, text);
+  return factsOf(program, text, comments.map(({ value, start }) => ({ value, start })));
 }

package/quality/architecture/facts.mjs

@@ -7,18 +7,60 @@
  * A node of the tree of oxc or of Babel. The nodes have many shapes, and the walk reads the fields of the two trees: they have no type.
  * @typedef {any} Node
  */
-/** @typedef {{ name: string | null; kind: string }} Export an exported name, and its kind */
-/** @typedef {{ name: string | null; readonly: boolean; value: string | null; asConst: boolean }} Property a property of a class */
-/** @typedef {{ name: string | null; exported: boolean; extends: string | null; implements: string[]; properties: Property[] }} Class */
-/** @typedef {{ chain: string[]; source: string }} Item an item of `export default [ … ]` */
-/** @typedef {{ name: string | null; args: (string | null)[] }} Call */
+/** Each fact that a rule points at has the number of its line in the file, from 1. */
+/** @typedef {{ name: string | null; kind: string; line: number }} Export an exported name, its kind, and its line */
+/** @typedef {{ name: string | null; readonly: boolean; value: string | null; asConst: boolean; line: number }} Property a property of a class */
+/** @typedef {{ name: string | null; text: string }} TypeName a type that a signature names: its name when it is a name (`Note`), and its text */
+/**
+ * A method of a class, and what it returns: each type of its return type, out of `Promise<…>` and of the unions (`Promise<A | B>` names A
+ * and B), or null when it has no return type.
+ * @typedef {{ name: string | null; returns: TypeName[] | null; line: number }} Method
+ */
+/** @typedef {{ name: string | null; exported: boolean; extends: string | null; implements: string[]; properties: Property[]; methods: Method[]; line: number }} Class */
+/**
+ * An item of `export default [ … ]`: the names that its chain calls, its text, the name that the first call takes first (`when(Event, …)`
+ * takes Event), the class of each `new X(…)` in it, and its line.
+ * @typedef {{ chain: string[]; source: string; subject: string | null; constructed: (string | null)[]; line: number }} Item
+ */
+/** @typedef {{ name: string; from: string; line: number }} Imported a name that the file imports, the module it comes from, and its line */
+/**
+ * A call: the name that it calls, the name that its chain starts from (`test` for `test.skip(…)`), its arguments that are strings, and its
+ * line.
+ * @typedef {{ name: string | null; root: string | null; args: (string | null)[]; line: number }} Call
+ */
+/**
+ * The lines of the facts that are strings, in the same order: `lines.imports[2]` is the line of `imports[2]`. A tag that Marko finds
+ * without an import counts as an import, at the line of the tag.
+ * @typedef {{ imports: number[]; constructed: number[]; objectTypes: number[]; tags: number[]; comments: number[] }} Lines
+ */
 /**
  * What the rules read in a file: see factsOf.
  * @typedef {{
- *   imports: string[]; exports: Export[]; defaultArray: Item[] | null; classes: Class[]; constructed: (string | null)[]; calls: Call[];
- *   objectTypes: string[]; strings: string[]; tags: string[]
+ *   imports: string[]; imported: Imported[]; exports: Export[]; defaultArray: Item[] | null; classes: Class[]; constructed: (string | null)[];
+ *   calls: Call[]; objectTypes: string[]; strings: string[]; tags: string[]; comments: string[]; lines: Lines
  * }} Facts
  */
+/** A comment that a parser gives apart from the tree: its text, and where it starts in the file. @typedef {{ value: string; start: number }} LooseComment */
+
+/**
+ * The number of the line (from 1) of a place in a text, from where the text starts: the offset of a node, or of a match.
+ * @param {string} text
+ * @returns {(offset: number) => number}
+ */
+export function linesIn(text) {
+  /** @type {number[]} */
+  const starts = [0];
+  for (let index = text.indexOf("\n"); index !== -1; index = text.indexOf("\n", index + 1)) starts.push(index + 1);
+  return offset => {
+    let low = 0;
+    let high = starts.length - 1;
+    while (low < high) {
+      const middle = Math.ceil((low + high) / 2);
+      if (starts[middle] <= offset) low = middle; else high = middle - 1;
+    }
+    return low + 1;
+  };
+}
 
 const SKIPPED_KEYS = new Set(["loc", "range", "start", "end", "extra", "leadingComments", "innerComments", "trailingComments", "comments"]);
 const WITH_SOURCE = new Set(["ImportDeclaration", "ExportNamedDeclaration", "ExportAllDeclaration", "ImportExpression"]);
@@ -34,6 +76,11 @@ const stringOf = node => {
 };
 /** @type {(node: Node) => string | null} */
 const nameOf = node => node?.type === "Identifier" ? node.name : node?.type === "MemberExpression" && !node.computed ? node.property.name : null;
+/** The name that a callee starts from: `test` for `test.skip`, `test.skipIf(x)` and `test.describe.only`. @type {(node: Node) => string | null} */
+const rootOf = node => {
+  while (node?.type === "MemberExpression" || node?.type === "CallExpression") node = node.type === "MemberExpression" ? node.object : node.callee;
+  return node?.type === "Identifier" ? node.name : null;
+};
 /** @type {(node: Node) => string | null} */
 const keyOf = node => node.key?.name ?? stringOf(node.key);
 
@@ -55,20 +102,41 @@ function chainOf(node) {
 }
 
 /**
+ * The name that the first call of a chain takes first: `when(Event, …)` and `bind(Port).to(Adapter)` take Event and Port.
  * @param {Node} node
+ * @returns {string | null}
+ */
+function subjectOf(node) {
+  while (node?.type === "CallExpression" && node.callee.type === "MemberExpression") node = node.callee.object;
+  return node?.type === "CallExpression" && node.arguments[0]?.type === "Identifier" ? node.arguments[0].name : null;
+}
+
+/**
+ * @param {Node} node
+ * @param {(node: Node) => number} lineOf
  * @returns {Export[]}
  */
-function exportsOf(node) {
-  if (node.type === "ExportDefaultDeclaration") return [{ name: "default", kind: "default" }];
-  if (node.type === "ExportAllDeclaration") return [{ name: node.exported ? nameOf(node.exported) ?? stringOf(node.exported) : "*", kind: "all" }];
+function exportsOf(node, lineOf) {
+  const line = lineOf(node);
+  if (node.type === "ExportDefaultDeclaration") return [{ name: "default", kind: "default", line }];
+  if (node.type === "ExportAllDeclaration") return [{ name: node.exported ? nameOf(node.exported) ?? stringOf(node.exported) : "*", kind: "all", line }];
   const { declaration } = node;
-  if (!declaration) return node.specifiers.map((/** @type {Node} */ specifier) => ({ name: nameOf(specifier.exported) ?? stringOf(specifier.exported), kind: "specifier" }));
-  if (declaration.type === "VariableDeclaration") return declaration.declarations.map((/** @type {Node} */ declarator) => ({ name: declarator.id.name, kind: declaration.kind }));
-  return [{ name: declaration.id?.name, kind: DECLARATION_KINDS[declaration.type] ?? declaration.type }];
+  if (!declaration) return node.specifiers.map((/** @type {Node} */ specifier) => ({ name: nameOf(specifier.exported) ?? stringOf(specifier.exported), kind: "specifier", line: lineOf(specifier) }));
+  if (declaration.type === "VariableDeclaration") return declaration.declarations.map((/** @type {Node} */ declarator) => ({ name: declarator.id.name, kind: declaration.kind, line: lineOf(declarator) }));
+  return [{ name: declaration.id?.name, kind: DECLARATION_KINDS[declaration.type] ?? declaration.type, line }];
 }
 
-/** @type {(node: Node, exported: boolean) => Class} */
-const classOf = (node, exported) => ({
+/** The types that a return type names: those of a union, and the type of a Promise. @type {(type: Node, text: string) => TypeName[]} */
+const typeNamesOf = (type, text) => {
+  if (type.type === "TSUnionType") return type.types.flatMap((/** @type {Node} */ member) => typeNamesOf(member, text));
+  const reference = type.type === "TSTypeReference" && type.typeName.type === "Identifier" ? type.typeName.name : null;
+  const [promised, ...others] = (type.typeArguments ?? type.typeParameters)?.params ?? [];
+  if (reference === "Promise" && promised && others.length === 0) return typeNamesOf(promised, text);
+  return [{ name: reference, text: text.slice(type.start, type.end) }];
+};
+
+/** @type {(node: Node, exported: boolean, lineOf: (node: Node) => number, text: string) => Class} */
+const classOf = (node, exported, lineOf, text) => ({
   name: node.id?.name ?? null,
   exported,
   extends: nameOf(node.superClass),
@@ -77,66 +145,125 @@ const classOf = (node, exported) => ({
     name: keyOf(member),
     readonly: Boolean(member.readonly),
     value: stringOf(member.value),
-    asConst: member.value?.type === "TSAsExpression" && member.value.typeAnnotation?.typeName?.name === "const"
-  }))
+    asConst: member.value?.type === "TSAsExpression" && member.value.typeAnnotation?.typeName?.name === "const",
+    line: lineOf(member)
+  })),
+  methods: node.body.body.filter((/** @type {Node} */ member) => (member.type === "MethodDefinition" || member.type === "ClassMethod") && member.kind === "method" && !member.static && !member.computed)
+    .map((/** @type {Node} */ member) => {
+      const returnType = (member.value ?? member).returnType?.typeAnnotation;
+      return { name: keyOf(member), returns: returnType ? typeNamesOf(returnType, text) : null, line: lineOf(member) };
+    }),
+  line: lineOf(node)
 });
 
 /**
  * - imports: every module the file imports or re-exports, dynamic imports included;
+ * - imported: each name that the file imports, with its module;
  * - exports: each exported name, with its kind (class, interface, type, const, function, enum, specifier, default, all);
- * - defaultArray: the items of `export default [ … ]`, with the calls of each item (`bind(X).to(Y)` calls bind, to), or null;
- * - classes: the classes, with what they extend and implement, and their properties;
+ * - defaultArray: the items of `export default [ … ]`, with the calls of each item (`bind(X).to(Y)` calls bind, to), the name that the first
+ *   call takes first (X), and the classes that the item builds, or null;
+ * - classes: the classes, with what they extend and implement, their properties, and the return types of their methods;
  * - constructed: the class of each `new X(…)`;
  * - calls: each call, with the value of its arguments that are strings (null for the others);
  * - objectTypes: the value of each `type: "…"` of an object literal;
  * - strings: every string of the code (comments and import paths aside);
- * - tags: the name of each Marko tag (Marko only).
+ * - tags: the name of each Marko tag (Marko only);
+ * - comments: the text of each comment: those that the parser gives, those that the tree holds, and the comments of a Marko template;
+ * - lines: the line of each import, `new`, `type: "…"`, tag and comment. The facts that are objects have their own line.
+ * A node of oxc has its offset in the text (start); a node of Babel has its line too (loc), which counts from the first line of the file.
  * @param {Node} program
  * @param {string} text
+ * @param {LooseComment[]} [comments] the comments that the parser gives apart from the tree (oxc)
  * @returns {Facts}
  */
-export function factsOf(program, text) {
+export function factsOf(program, text, comments = []) {
+  const lineAt = linesIn(text);
+  /** @type {(node: Node) => number} */
+  const lineOf = node => node.loc?.start?.line ?? lineAt(node.start ?? 0);
   /** @type {Facts} */
-  const facts = { imports: [], exports: [], defaultArray: null, classes: [], constructed: [], calls: [], objectTypes: [], strings: [], tags: [] };
+  const facts = {
+    imports: [], imported: [], exports: [], defaultArray: null, classes: [], constructed: [], calls: [], objectTypes: [], strings: [], tags: [],
+    comments: comments.map(({ value }) => value),
+    lines: { imports: [], constructed: [], objectTypes: [], tags: [], comments: comments.map(({ start }) => lineAt(start)) }
+  };
+  /** @type {(source: string, node: Node) => void} */
+  const addImport = (source, node) => {
+    facts.imports.push(source);
+    facts.lines.imports.push(lineOf(node));
+  };
+  const seenComments = new WeakSet();
   const exportedClasses = new WeakSet();
   const seen = new WeakSet();
+  /** @type {{ node: Node; item: Item }[]} */
+  const items = [];
 
   /** @param {Node} node */
   const visit = node => {
     if (WITH_SOURCE.has(node.type)) {
       const source = stringOf(node.source);
-      if (source !== null) facts.imports.push(source);
+      if (source !== null) addImport(source, node);
+      if (source !== null && node.type === "ImportDeclaration") {
+        for (const specifier of node.specifiers) facts.imported.push({ name: specifier.local.name, from: source, line: lineOf(specifier) });
+      }
     }
     if (node.type === "TSImportType") {
       const source = stringOf(node.source ?? node.argument);
-      if (source !== null) facts.imports.push(source);
+      if (source !== null) addImport(source, node);
     }
     if (node.type === "CallExpression" && node.callee.type === "Import") {
       const source = stringOf(node.arguments[0]);
-      if (source !== null) facts.imports.push(source);
+      if (source !== null) addImport(source, node);
     }
     if (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration" || node.type === "ExportAllDeclaration") {
-      facts.exports.push(...exportsOf(node));
+      facts.exports.push(...exportsOf(node, lineOf));
       if (node.declaration?.type === "ClassDeclaration") exportedClasses.add(node.declaration);
       if (node.type === "ExportDefaultDeclaration" && node.declaration.type === "ArrayExpression") {
-        facts.defaultArray = node.declaration.elements.map((/** @type {Node} */ item) => ({ chain: chainOf(item), source: item ? text.slice(item.start, item.end).replace(/\s+/g, " ") : "" }));
+        facts.defaultArray = node.declaration.elements.map((/** @type {Node} */ element) => {
+          /** @type {Item} */
+          const item = {
+            chain: chainOf(element), source: element ? text.slice(element.start, element.end).replace(/\s+/g, " ") : "", subject: subjectOf(element), constructed: [],
+            line: lineOf(element ?? node)
+          };
+          if (element) items.push({ node: element, item });
+          return item;
+        });
       }
     }
-    if (node.type === "ClassDeclaration") facts.classes.push(classOf(node, exportedClasses.has(node)));
-    if (node.type === "NewExpression") facts.constructed.push(nameOf(node.callee));
-    if (node.type === "CallExpression") facts.calls.push({ name: nameOf(node.callee), args: node.arguments.map(stringOf) });
+    if (node.type === "ClassDeclaration") facts.classes.push(classOf(node, exportedClasses.has(node), lineOf, text));
+    if (node.type === "NewExpression") {
+      facts.constructed.push(nameOf(node.callee));
+      facts.lines.constructed.push(lineOf(node));
+      for (const { node: element, item } of items) if (element.start <= node.start && node.end <= element.end) item.constructed.push(nameOf(node.callee));
+    }
+    if (node.type === "CallExpression") facts.calls.push({ name: nameOf(node.callee), root: rootOf(node.callee), args: node.arguments.map(stringOf), line: lineOf(node) });
     if (node.type === "ObjectExpression") {
       for (const property of node.properties) {
         const type = stringOf(property.value);
         if ((property.type === "Property" || property.type === "ObjectProperty") && !property.computed && keyOf(property) === "type" && type !== null) {
           facts.objectTypes.push(type);
+          facts.lines.objectTypes.push(lineOf(node));
         }
       }
     }
     if ((node.type === "Literal" || node.type === "StringLiteral") && typeof node.value === "string") facts.strings.push(node.value);
     if (node.type === "TemplateElement") facts.strings.push(node.value.cooked);
     const tag = node.type === "MarkoTag" ? stringOf(node.name) : null;
-    if (tag !== null) facts.tags.push(tag);
+    if (tag !== null) {
+      facts.tags.push(tag);
+      facts.lines.tags.push(lineOf(node));
+    }
+    // Babel hangs the comments on the nodes next to them, a comment on two nodes at times; a comment of a Marko template is a node.
+    for (const comment of [node.leadingComments, node.innerComments, node.trailingComments].flat()) {
+      if (comment && !seenComments.has(comment)) {
+        seenComments.add(comment);
+        facts.comments.push(comment.value);
+        facts.lines.comments.push(lineOf(comment));
+      }
+    }
+    if (node.type === "MarkoComment") {
+      facts.comments.push(node.value);
+      facts.lines.comments.push(lineOf(node));
+    }
   };
 
   /** @type {(node: Node, parentType?: string, key?: string) => void} */