tina4-nodejs 3.13.36 → 3.13.38

package/packages/core/src/messenger.ts

@@ -28,6 +28,19 @@ import tls from "node:tls";
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { randomUUID } from "node:crypto";
+import { isTruthy } from "./dotenv.js";
+import { Log } from "./logger.js";
+
+/**
+ * TLS certificate validation defaults to SECURE (rejectUnauthorized: true).
+ * Set TINA4_MAIL_TLS_INSECURE=true to disable validation for dev / self-signed
+ * certificates ONLY — never in production. Previously this was hard-coded to
+ * `rejectUnauthorized: false`, silently disabling certificate validation for
+ * every TLS connection (a man-in-the-middle risk).
+ */
+function tlsRejectUnauthorized(): boolean {
+  return !isTruthy(process.env.TINA4_MAIL_TLS_INSECURE);
+}
 
 // ── Types ────────────────────────────────────────────────────
 
@@ -37,6 +50,23 @@ export interface SendResult {
   id?: string;
 }
 
+/**
+ * Raised when an IMAP read fails to connect, authenticate, or speak the
+ * protocol (a `NO`/`BAD` tagged response, a refused/reset socket, a TLS or
+ * DNS failure). Distinct from a SUCCESSFUL fetch that simply has no messages —
+ * that still returns an empty result ([] / 0 / {}), NOT an error.
+ *
+ * inbox()/read()/unread()/search()/folders() LOG and then RAISE this on a
+ * connection/protocol failure so a dead mailbox is never silently mistaken for
+ * an empty one. send() is unchanged — it keeps returning { success, error }.
+ */
+export class MessengerConnectionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MessengerConnectionError";
+  }
+}
+
 export interface EmailMessage {
   id: string;
   type: "inbox" | "outbox";
@@ -402,7 +432,7 @@ export class Messenger {
 
       if (this.port === 465) {
         // Implicit TLS (SMTPS)
-        socket = tls.connect({ host: this.host, port: this.port, rejectUnauthorized: false });
+        socket = tls.connect({ host: this.host, port: this.port, rejectUnauthorized: tlsRejectUnauthorized() });
         await new Promise<void>((resolve, reject) => {
           socket.once("secureConnect", resolve);
           socket.once("error", reject);
@@ -440,7 +470,7 @@ export class Messenger {
         // Upgrade to TLS
         const plainSocket = socket as net.Socket;
         socket = tls.connect(
-          { socket: plainSocket, host: this.host, rejectUnauthorized: false },
+          { socket: plainSocket, host: this.host, rejectUnauthorized: tlsRejectUnauthorized() },
         );
         await new Promise<void>((resolve, reject) => {
           (socket as tls.TLSSocket).once("secureConnect", resolve);
@@ -541,7 +571,7 @@ export class Messenger {
       let socket: net.Socket | tls.TLSSocket;
 
       if (this.port === 465) {
-        socket = tls.connect({ host: this.host, port: this.port, rejectUnauthorized: false });
+        socket = tls.connect({ host: this.host, port: this.port, rejectUnauthorized: tlsRejectUnauthorized() });
         await new Promise<void>((resolve, reject) => {
           socket.once("secureConnect", resolve);
           socket.once("error", reject);
@@ -595,7 +625,7 @@ export class Messenger {
       || (this.imapEncryption === "" && this.imapPort === 993);
 
     if (useTls) {
-      socket = tls.connect({ host: this.imapHost, port: this.imapPort, rejectUnauthorized: false });
+      socket = tls.connect({ host: this.imapHost, port: this.imapPort, rejectUnauthorized: tlsRejectUnauthorized() });
       await new Promise<void>((resolve, reject) => {
         socket.once("secureConnect", resolve);
         socket.once("error", reject);
@@ -638,7 +668,12 @@ export class Messenger {
    * Returns list of message summaries.
    */
   async inbox(limit: number = 20, offset: number = 0, folder: string = "INBOX"): Promise<ImapMessage[]> {
-    const socket = await this.imapConnect();
+    let socket: net.Socket | tls.TLSSocket;
+    try {
+      socket = await this.imapConnect();
+    } catch (err) {
+      throw imapFail("inbox", err);
+    }
     try {
       // Select folder
       await imapCommand(socket, `SELECT ${imapQuote(folder)}`);
@@ -660,6 +695,8 @@ export class Messenger {
       }
 
       return messages;
+    } catch (err) {
+      throw imapFail("inbox", err);
     } finally {
       await this.imapDisconnect(socket);
     }
@@ -669,15 +706,28 @@ export class Messenger {
    * Read a single message by sequence number or UID.
    */
   async read(uid: string, folder: string = "INBOX"): Promise<ImapFullMessage> {
-    const socket = await this.imapConnect();
+    let socket: net.Socket | tls.TLSSocket;
+    try {
+      socket = await this.imapConnect();
+    } catch (err) {
+      throw imapFail("read", err);
+    }
     try {
       await imapCommand(socket, `SELECT ${imapQuote(folder)}`);
       const fetchResp = await imapCommand(socket, `FETCH ${uid} (FLAGS BODY[])`);
 
+      // A genuinely missing UID is a tagged OK with no message body literal —
+      // that is NOT an error: return an empty message (parity with Python's {}).
+      if (!/\{\d+\}/.test(fetchResp)) {
+        return emptyFullMessage(uid);
+      }
+
       // Mark as seen
       await imapCommand(socket, `STORE ${uid} +FLAGS (\\Seen)`);
 
       return parseFullMessage(uid, fetchResp);
+    } catch (err) {
+      throw imapFail("read", err);
     } finally {
       await this.imapDisconnect(socket);
     }
@@ -704,7 +754,12 @@ export class Messenger {
     if (unseenOnly) criteria.push("UNSEEN");
 
     const query = criteria.join(" ");
-    const socket = await this.imapConnect();
+    let socket: net.Socket | tls.TLSSocket;
+    try {
+      socket = await this.imapConnect();
+    } catch (err) {
+      throw imapFail("search", err);
+    }
     try {
       await imapCommand(socket, `SELECT ${imapQuote(folder)}`);
       const searchResp = await imapCommand(socket, `SEARCH ${query}`);
@@ -718,6 +773,8 @@ export class Messenger {
         messages.push(parseHeaderResponse(uid, fetchResp));
       }
       return messages;
+    } catch (err) {
+      throw imapFail("search", err);
     } finally {
       await this.imapDisconnect(socket);
     }
@@ -754,11 +811,18 @@ export class Messenger {
    * Count unseen messages in a folder.
    */
   async unread(folder: string = "INBOX"): Promise<number> {
-    const socket = await this.imapConnect();
+    let socket: net.Socket | tls.TLSSocket;
+    try {
+      socket = await this.imapConnect();
+    } catch (err) {
+      throw imapFail("unread", err);
+    }
     try {
       await imapCommand(socket, `SELECT ${imapQuote(folder)}`);
       const searchResp = await imapCommand(socket, "SEARCH UNSEEN");
       return parseSearchResponse(searchResp).length;
+    } catch (err) {
+      throw imapFail("unread", err);
     } finally {
       await this.imapDisconnect(socket);
     }
@@ -768,7 +832,12 @@ export class Messenger {
    * List available IMAP folders/mailboxes.
    */
   async folders(): Promise<string[]> {
-    const socket = await this.imapConnect();
+    let socket: net.Socket | tls.TLSSocket;
+    try {
+      socket = await this.imapConnect();
+    } catch (err) {
+      throw imapFail("folders", err);
+    }
     try {
       const resp = await imapCommand(socket, 'LIST "" "*"');
       const result: string[] = [];
@@ -778,6 +847,8 @@ export class Messenger {
         if (m) result.push(m[1]);
       }
       return result;
+    } catch (err) {
+      throw imapFail("folders", err);
     } finally {
       await this.imapDisconnect(socket);
     }
@@ -840,11 +911,20 @@ function imapCommand(socket: net.Socket | tls.TLSSocket, command: string): Promi
     let buffer = "";
     const onData = (chunk: Buffer) => {
       buffer += chunk.toString("utf-8");
-      // Look for tagged response line indicating completion
-      if (buffer.includes(`${tag} OK`) || buffer.includes(`${tag} NO`) || buffer.includes(`${tag} BAD`)) {
+      // Tagged OK = success.
+      if (buffer.includes(`${tag} OK`)) {
         socket.removeListener("data", onData);
         socket.removeListener("error", onError);
         resolve(buffer);
+        return;
+      }
+      // Tagged NO / BAD = protocol failure — fail loud (mirrors Python's
+      // non-OK status raise). A genuinely empty mailbox is a tagged OK with an
+      // empty SEARCH result, which still resolves above.
+      if (buffer.includes(`${tag} NO`) || buffer.includes(`${tag} BAD`)) {
+        socket.removeListener("data", onData);
+        socket.removeListener("error", onError);
+        reject(new MessengerConnectionError(`IMAP command failed: ${command.split(" ")[0]} → ${buffer.trim()}`));
       }
     };
 
@@ -859,6 +939,17 @@ function imapCommand(socket: net.Socket | tls.TLSSocket, command: string): Promi
   });
 }
 
+/**
+ * Log an IMAP connection/protocol failure and return the error to throw.
+ * A genuinely empty mailbox is NOT an error and never reaches here.
+ */
+function imapFail(method: string, err: unknown): MessengerConnectionError {
+  const e = err instanceof Error ? err : new Error(String(err));
+  Log.error(`Messenger IMAP ${method}() failed: ${e.name}: ${e.message}`);
+  if (e instanceof MessengerConnectionError) return e;
+  return new MessengerConnectionError(`IMAP ${method} failed: ${e.message}`);
+}
+
 function parseSearchResponse(response: string): string[] {
   // SEARCH response: * SEARCH 1 2 3 4 5
   const match = response.match(/\* SEARCH (.+)/);
@@ -898,6 +989,15 @@ function parseHeaderResponse(uid: string, response: string): ImapMessage {
   };
 }
 
+/**
+ * An empty full message — returned when a FETCH succeeds (tagged OK) but the
+ * UID does not exist, so there is no message body. Mirrors Python's {} return:
+ * a missing UID is NOT an error.
+ */
+function emptyFullMessage(uid: string): ImapFullMessage {
+  return { uid, subject: "", from: "", to: "", cc: "", date: "", bodyText: "", bodyHtml: "", headers: {} };
+}
+
 function parseFullMessage(uid: string, response: string): ImapFullMessage {
   // Extract the raw message body from FETCH response
   const bodyMatch = response.match(/\{(\d+)\}\r\n([\s\S]*)/);

package/packages/core/src/metrics.ts

@@ -59,20 +59,74 @@ let _lastScanRoot = "";
 
 // ── Test file detection ─────────────────────────────────────
 
+/** Escape a string for safe embedding inside a RegExp source. */
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Top-level classes DEFINED in a source file. A test that references one of
+ * these genuinely exercises this file. Classes only (distinctive PascalCase,
+ * length > 3) — module-level function names like `get`/`run`/`init` are too
+ * generic to trust as a coverage signal.
+ */
+function definedClasses(source: string): Set<string> {
+  const names = new Set<string>();
+  const re = /(?:^|\n)\s*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+(\w+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(source)) !== null) {
+    const name = m[1];
+    if (name && !name.startsWith("_") && name.length > 3) {
+      names.add(name);
+    }
+  }
+  return names;
+}
+
+/**
+ * Whether a source file has a test that ACTUALLY exercises it.
+ *
+ * PRECISE detection — a bare word-mention of the module name is NOT enough
+ * (that over-reported badly: a default DB adapter looked "tested" because some
+ * test merely said the word "sqlite"). A file counts as covered only on a real,
+ * file-specific signal:
+ *
+ *   1. Filename — a dedicated test file named for THIS exact module
+ *      (`<m>.test.ts/.js`, `<m>.spec.ts/.js`, `test_<m>.*`, `<m>_test.*`,
+ *      `<m>_spec.*`) — NOT the parent directory (one `database.test.ts` must
+ *      not mark every file under `adapters/` tested).
+ *   2. Import — a test that actually IMPORTS this module by its path
+ *      (`import … from ".../<m>.js"`, `require(".../<m>")`).
+ *   3. Class reference — a test that references a top-level class DEFINED in
+ *      this file (distinctive PascalCase, length > 3). NO bare module-name word
+ *      match and NO guessed CamelCase-from-snake_case match.
+ *
+ * Returns true only on a real signal, so the "untested" offenders surfaced by
+ * `tina4 metrics` and the dashboard "T" badge are trustworthy.
+ */
 function hasMatchingTest(relPath: string): boolean {
-  const parts = relPath.split('/');
-  const basename = parts[parts.length - 1] || '';
-  const name = basename.replace(/\.(ts|js)$/, '');
-  const parentModule = parts.length > 1 ? parts[parts.length - 2] : '';
+  const parts = relPath.split("/");
+  const basename = parts[parts.length - 1] || "";
+  const name = basename.replace(/\.(ts|js)$/, "");
+
+  // Classes defined in THIS file (read from the resolved on-disk file).
+  let symbols = new Set<string>();
+  const srcFile = _lastScanRoot ? path.join(_lastScanRoot, relPath) : relPath;
+  const srcText = readFileSafe(srcFile) ?? readFileSafe(relPath);
+  if (srcText !== null) {
+    symbols = definedClasses(srcText);
+  }
 
-  // Search both CWD and the scan root (framework dir when in fallback mode)
+  // Search CWD and (in framework-fallback mode) the repo root that owns test/.
   const searchRoots = [process.cwd()];
   if (_lastScanRoot && _lastScanRoot !== process.cwd()) {
-    // Go up from scan root to find the repo root (where test/ lives)
     let repoRoot = _lastScanRoot;
-    // Walk up until we find a test/ or tests/ dir, max 5 levels
     for (let i = 0; i < 5; i++) {
-      if (fs.existsSync(path.join(repoRoot, 'test')) || fs.existsSync(path.join(repoRoot, 'tests')) || fs.existsSync(path.join(repoRoot, 'spec'))) {
+      if (
+        fs.existsSync(path.join(repoRoot, "test")) ||
+        fs.existsSync(path.join(repoRoot, "tests")) ||
+        fs.existsSync(path.join(repoRoot, "spec"))
+      ) {
         searchRoots.push(repoRoot);
         break;
       }
@@ -82,10 +136,10 @@ function hasMatchingTest(relPath: string): boolean {
     }
   }
 
-  const testDirs = ['test', 'tests', 'spec'];
+  const testDirs = ["test", "tests", "spec"];
 
+  // Stage 1: a dedicated test FILE named for THIS module (no parent-dir blanket).
   for (const root of searchRoots) {
-    // Stage 1: Filename matching
     for (const td of testDirs) {
       const patterns = [
         path.join(root, td, `${name}.test.ts`),
@@ -94,39 +148,49 @@ function hasMatchingTest(relPath: string): boolean {
         path.join(root, td, `${name}.spec.js`),
         path.join(root, td, `test_${name}.ts`),
         path.join(root, td, `test_${name}.js`),
-        path.join(root, td, `test_${name}.py`),
-        path.join(root, td, `${name}_test.rb`),
-        path.join(root, td, `${name}_spec.rb`),
-        ...(parentModule && parentModule !== name ? [
-          path.join(root, td, `${parentModule}.test.ts`),
-          path.join(root, td, `${parentModule}.test.js`),
-          path.join(root, td, `${parentModule}.spec.ts`),
-        ] : []),
+        path.join(root, td, `${name}_test.ts`),
+        path.join(root, td, `${name}_test.js`),
+        path.join(root, td, `${name}_spec.ts`),
+        path.join(root, td, `${name}_spec.js`),
       ];
-      if (patterns.some(p => fs.existsSync(p))) return true;
+      if (patterns.some((p) => fs.existsSync(p))) return true;
     }
+  }
 
-    // Stage 2+3: Content scan
-    const pathWithoutExt = relPath.replace(/\.(ts|js|py|rb|php)$/, '');
-    const className = name
-      .replace(/[-_](.)/g, (_: string, c: string) => c.toUpperCase())
-      .replace(/^(.)/, (_: string, c: string) => c.toUpperCase());
+  // Stage 2+3: a test that actually IMPORTS this module (by path), or references
+  // a class DEFINED in it. NO bare word-of-the-module-name match.
+  // A module specifier whose final path segment is exactly this module name:
+  //   "./<name>", "../a/b/<name>.js", "@pkg/<name>" — but NOT "better-<name>"
+  //   (the segment boundary is the opening quote or a "/", never a hyphen/word
+  //   char). Optional .ts/.js extension.
+  const spec = `["'](?:[^"']*\\/)?${escapeRegExp(name)}(?:\\.(?:ts|js))?["']`;
+  const importRes: RegExp[] = [
+    // import ... from "<spec>"
+    new RegExp(`import\\b[^;\\n]*?from\\s*${spec}`),
+    // require("<spec>")
+    new RegExp(`require\\s*\\(\\s*${spec}\\s*\\)`),
+    // side-effect import "<spec>"
+    new RegExp(`import\\s*${spec}`),
+  ];
+
+  let classRe: RegExp | null = null;
+  if (symbols.size > 0) {
+    const alt = [...symbols].map(escapeRegExp).join("|");
+    classRe = new RegExp(`\\b(?:${alt})\\b`);
+  }
 
+  for (const root of searchRoots) {
     for (const td of testDirs) {
       const fullTd = path.join(root, td);
       if (!fs.existsSync(fullTd)) continue;
-      const testFiles = walkFiles(fullTd, ['.ts', '.js', '.py', '.rb']);
+      const testFiles = walkFiles(fullTd, [".ts", ".js"]);
       for (const testFile of testFiles) {
+        // Never let a file count as its own test.
+        if (path.resolve(testFile) === path.resolve(srcFile)) continue;
         const content = readFileSafe(testFile);
         if (content === null) continue;
-        if (content.includes(name) && (
-          content.includes(`"${name}"`) || content.includes(`'${name}'`) ||
-          content.includes(`/${name}"`) || content.includes(`/${name}'`) ||
-          content.includes(pathWithoutExt)
-        )) return true;
-        if (className !== name && new RegExp(`\\b${className.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(content)) {
-          return true;
-        }
+        if (importRes.some((re) => re.test(content))) return true;
+        if (classRe && classRe.test(content)) return true;
       }
     }
   }
@@ -871,6 +935,141 @@ export function fullAnalysis(root: string = "src"): Record<string, any> {
   return result;
 }
 
+// ── Top Offenders (CLI + dashboard) ──────────────────────────
+
+/** Severity ranking for sorting (higher = more severe). */
+export const SEVERITY_RANK: Record<string, number> = { error: 2, warn: 1, info: 0 };
+
+export interface Offender {
+  file: string;
+  line: number;
+  kind: string;
+  severity: "error" | "warn" | "info";
+  score: number;
+  detail: string;
+}
+
+export interface OffendersResult {
+  offenders: Offender[];
+  summary: Record<string, any>;
+}
+
+/**
+ * Rank the worst code-quality issues into a single "top offenders" list.
+ *
+ * Reuses {@link fullAnalysis} (does NOT re-analyze — the result is mtime-cached).
+ * Each offender is `{ file, line, kind, severity, score, detail }`.
+ *
+ * Rules (one offender per matching condition — SAME scoring as the master):
+ *   - function complexity > 10  → kind "complexity"
+ *         severity "error" if > 20 else "warn"; score = complexity
+ *   - file loc > 500            → kind "large_file" (warn); score = loc / 100
+ *   - file functions > 20       → kind "too_many_functions" (warn); score = functions / 4
+ *   - file maintainability < 40 → kind "low_maintainability"
+ *         severity "error" if < 20 else "warn"; score = 50 - mi
+ *   - file has_tests === false  → kind "untested" (info); score = loc / 100
+ *
+ * Sorted by (severity rank, score) DESCENDING and truncated to `top`.
+ *
+ * Returns `{ offenders, summary }` where summary carries the headline numbers
+ * the CLI prints (files_analyzed, total_functions, avg_complexity,
+ * avg_maintainability, scan_mode, scan_root, total_offenders).
+ */
+export function offenders(root: string = "src", top: number = 20): OffendersResult {
+  const analysis = fullAnalysis(root);
+  if (analysis.error) {
+    return { offenders: [], summary: { error: analysis.error } };
+  }
+
+  const items: Offender[] = [];
+
+  // Function-level: cyclomatic complexity.
+  for (const fn of analysis.most_complex_functions || []) {
+    const cc: number = fn.complexity;
+    if (cc > 10) {
+      items.push({
+        file: fn.file,
+        line: fn.line,
+        kind: "complexity",
+        severity: cc > 20 ? "error" : "warn",
+        score: cc,
+        detail: `${fn.name} — cyclomatic complexity ${cc}`,
+      });
+    }
+  }
+
+  // File-level rules.
+  for (const fm of analysis.file_metrics || []) {
+    const filePath: string = fm.path;
+    const loc: number = fm.loc;
+    const funcs: number = fm.functions;
+    const mi: number = fm.maintainability;
+
+    if (loc > 500) {
+      items.push({
+        file: filePath,
+        line: 1,
+        kind: "large_file",
+        severity: "warn",
+        score: loc / 100,
+        detail: `${loc} LOC (max 500)`,
+      });
+    }
+
+    if (funcs > 20) {
+      items.push({
+        file: filePath,
+        line: 1,
+        kind: "too_many_functions",
+        severity: "warn",
+        score: funcs / 4,
+        detail: `${funcs} functions (max 20)`,
+      });
+    }
+
+    if (mi < 40) {
+      items.push({
+        file: filePath,
+        line: 1,
+        kind: "low_maintainability",
+        severity: mi < 20 ? "error" : "warn",
+        score: 50 - mi,
+        detail: `maintainability index ${mi} (min 40)`,
+      });
+    }
+
+    if (fm.has_tests === false) {
+      items.push({
+        file: filePath,
+        line: 1,
+        kind: "untested",
+        severity: "info",
+        score: loc / 100,
+        detail: "no referencing test",
+      });
+    }
+  }
+
+  // Sort by (severity rank, score) DESCENDING.
+  items.sort((a, b) => {
+    const sevDiff = SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity];
+    if (sevDiff !== 0) return sevDiff;
+    return b.score - a.score;
+  });
+
+  const summary = {
+    files_analyzed: analysis.files_analyzed,
+    total_functions: analysis.total_functions,
+    avg_complexity: analysis.avg_complexity,
+    avg_maintainability: analysis.avg_maintainability,
+    scan_mode: analysis.scan_mode,
+    scan_root: analysis.scan_root,
+    total_offenders: items.length,
+  };
+
+  return { offenders: items.slice(0, top), summary };
+}
+
 // ── File Detail ──────────────────────────────────────────────
 
 export function fileDetail(filePath: string): Record<string, any> {