Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

16.5 KB
Raw Blame
/**
 * Text-level primitives shared by the whole-tree source-scan guard suites —
 * `childProcess.guards.test.js`, `timerCallbackConventions.test.js` and
 * `sockets/asyncHandlerGuard.test.js`.
 *
 * Those guards enforce structural rules no runtime test can reach ("every spawn
 * goes through the wrapper", "every await outside the request lifecycle owns its
 * rejection"), so each one reads source as text and each one needs the same
 * three things: literals and comments neutralised, so a rule *described* in
 * prose can neither satisfy nor defeat the scan and a `}` inside a string cannot
 * skew a brace walk; a bracket matcher, so a construct split across lines is
 * captured WHOLE rather than by a fixed character window (a window reads the
 * next statement and attributes it to the current one); and one definition of
 * "this await owns its rejection", so the timer rule and the socket rule cannot
 * drift apart.
 *
 * Lexer-assisted, not an AST pass: a real parser would be more precise, but
 * these guards run over ~1500 files on every `npm test`, and their false
 * positives are loud and one line to fix. The limits are listed on
 * `unguardedAwaits` and in `timerCallbackConventions.test.js`'s header.
 */

/**
 * Blank comment LINES while preserving line count, so a rule can be *described*
 * in a comment without the guard flagging the description as a violation
 * (`cosHealthMonitor.js` explains the pm2 rule using the banned pattern).
 *
 * Line-based, and so weaker than `blankLiterals` — it is the right tool only for
 * a rule matched per line, where every real hit outside the wrapper is a JSDoc
 * `@param {import('child_process').ChildProcess}` line and a false positive is
 * loud and one line to fix.
 * @param {string} src
 * @returns {string[]} one entry per input line, comment lines replaced by ''
 */
export function blankComments(src) {
  return src.split('\n').map((line) => (/^\s*(\/\/|\*|\/\*)/.test(line) ? '' : line));
}

// Keywords a regex literal may directly follow. A `/` after one of these is
// never division, because a keyword cannot be an operand — `await /[)]/.test(s)`
// and `return /a/` both open a regex. Reading one as division blanked nothing,
// so the regex body's own brackets skewed the caller's bracket walk.
//
// RESERVED WORDS ONLY, and the two errors are not symmetrical. Missing a real
// regex context restores the old behavior: the literal is read as division,
// nothing is blanked, and the scan is conservative. Listing a word that can
// also be an IDENTIFIER is corrupting: `const of = 4; f(of / n)` would lex the
// division as a regex opener and blank the rest of the line, hiding whatever
// came after it. So `of` — a contextual keyword and a legal identifier — is
// deliberately absent, while `await` and `yield` are in: every source these
// guards read is an ES module, where both are reserved.
const KEYWORDS_BEFORE_REGEX = new Set([
  'await', 'case', 'default', 'delete', 'do', 'else', 'extends', 'in',
  'instanceof', 'new', 'return', 'throw', 'typeof', 'void', 'yield',
]);

// Anything that can appear inside an identifier, Unicode included: `café`
// ends in `e`, and an ASCII-only boundary would read `naïvereturn` as ending
// in the keyword `return`.
const IDENTIFIER_CHAR = /[\p{ID_Continue}$]/u;

/**
 * The identifier ending at `end` (exclusive) in the character ARRAY `chars`, or
 * '' when what ends there is not a bare identifier. Reads the PARTIALLY
 * BLANKED output, so a keyword spelled inside an already-blanked string or
 * comment is invisible here — which is the point.
 */
function wordEndingAt(chars, end) {
  let start = end;
  while (start > 0 && IDENTIFIER_CHAR.test(chars[start - 1])) start -= 1;
  // `obj.return` is a property read and `this.#return` a private field: both
  // are VALUES, so a `/` after one divides. Reading either as the keyword lexes
  // that division as a regex opener and blanks the rest of the line.
  if (start > 0 && (chars[start - 1] === '.' || chars[start - 1] === '#')) return '';
  return chars.slice(start, end).join('');
}

/**
 * True when a `/` at this position opens a regex literal rather than division.
 * A regex can only follow a position where an operand cannot: an operator, an
 * opening bracket, a statement boundary, a keyword, or the start of the file.
 */
function regexCanStartAfter(prev, chars, at) {
  if (prev === '' || '(,=:[!&|?{};+-*%~^<>'.includes(prev)) return true;
  if (!IDENTIFIER_CHAR.test(prev)) return false;
  // Step back over the whitespace between the keyword and the `/`.
  let end = at;
  while (end > 0 && /\s/.test(chars[end - 1])) end -= 1;
  return KEYWORDS_BEFORE_REGEX.has(wordEndingAt(chars, end));
}

// One state machine for both public modes and the paired-view scan. Only the
// paired view assembles the comment-only output from spans; legacy callers
// keep one output array.
function lexSource(src, { keepLiteralText = false, includeCommentOnly = false } = {}) {
  const out = src.split('');
  const comments = includeCommentOnly ? [] : null;
  let commentEnd = 0;
  const n = src.length;
  const blank = (i) => { if (i < n && src[i] !== '\n') out[i] = ' '; };
  const recordComment = (start, end) => {
    if (!comments) return;
    const until = Math.min(end, n);
    comments.push(src.slice(commentEnd, start), out.slice(start, until).join(''));
    commentEnd = until;
  };
  // Blanks a character belonging to a LITERAL rather than to a comment.
  const blankLit = keepLiteralText ? () => {} : blank;
  // Brace depths of the code regions opened by `${` inside template literals,
  // so a nested template resumes correctly at its closing `}`.
  const templateStack = [];
  let inTemplate = false;
  let braceDepth = 0;
  // A `/` starts a regex only where a value cannot precede it. Tracking the last
  // significant character is the standard heuristic and is what keeps a
  // character class like /["']/ from being read as a string opener.
  let prevSignificant = '';
  let i = 0;

  while (i < n) {
    const c = src[i];

    if (inTemplate) {
      if (c === '\\') { blankLit(i); blankLit(i + 1); i += 2; continue; }
      if (c === '`') { blankLit(i); i += 1; inTemplate = false; prevSignificant = '`'; continue; }
      if (c === '$' && src[i + 1] === '{') {
        blankLit(i); blankLit(i + 1); i += 2;
        templateStack.push(braceDepth);
        braceDepth = 0;
        inTemplate = false;
        prevSignificant = '{';
        continue;
      }
      blankLit(i); i += 1; continue;
    }

    if (c === '/' && src[i + 1] === '/') {
      const start = i;
      while (i < n && src[i] !== '\n') { blank(i); i += 1; }
      recordComment(start, i);
      continue;
    }
    if (c === '/' && src[i + 1] === '*') {
      const start = i;
      while (i < n && !(src[i] === '*' && src[i + 1] === '/')) { blank(i); i += 1; }
      blank(i); blank(i + 1); i += 2;
      recordComment(start, i);
      continue;
    }
    if (c === "'" || c === '"') {
      const quote = c;
      blankLit(i); i += 1;
      while (i < n && src[i] !== quote) {
        if (src[i] === '\\') { blankLit(i); i += 1; }
        blankLit(i); i += 1;
      }
      blankLit(i); i += 1;
      prevSignificant = quote;
      continue;
    }
    if (c === '`') { blankLit(i); i += 1; inTemplate = true; continue; }
    if (c === '/' && regexCanStartAfter(prevSignificant, out, i)) {
      blankLit(i); i += 1;
      let inClass = false;
      while (i < n && src[i] !== '\n') {
        if (src[i] === '\\') { blankLit(i); blankLit(i + 1); i += 2; continue; }
        if (src[i] === '[') inClass = true;
        else if (src[i] === ']') inClass = false;
        else if (src[i] === '/' && !inClass) break;
        blankLit(i); i += 1;
      }
      blankLit(i); i += 1;
      // Blank the flags too so `gi` can't be read as an identifier.
      while (i < n && /[a-z]/.test(src[i])) { blankLit(i); i += 1; }
      prevSignificant = ')';
      continue;
    }

    if (c === '{') braceDepth += 1;
    else if (c === '}') {
      if (braceDepth === 0 && templateStack.length > 0) {
        // Closes a `${…}` hole, so it is part of the template literal.
        blankLit(i); i += 1;
        braceDepth = templateStack.pop();
        inTemplate = true;
        continue;
      }
      braceDepth -= 1;
    }
    if (!/\s/.test(c)) prevSignificant = c;
    i += 1;
  }

  const blanked = out.join('');
  return comments ? { blanked, code: comments.join('') + src.slice(commentEnd) } : blanked;
}

/**
 * Replace the contents of comments, string/template literals, and regex
 * literals with spaces, preserving LENGTH so every index still maps back to the
 * original source. Everything downstream (bracket walks, `await` matching) then
 * sees code only — and a caller that needs a literal's text (a socket event
 * name, say) can still read it out of the original string at the same offset.
 * @param {string} src
 * @param {{keepLiteralText?: boolean, includeCommentOnly?: boolean}} [options] `keepLiteralText` leaves
 *   string/template/regex CONTENT in place and blanks only comments — reach it
 *   through `blankCommentBodies`. The lex is identical either way, so the two
 *   modes cannot disagree about where a comment ends and a literal begins.
 *   `includeCommentOnly` returns both `{ code, blanked }` views from one
 *   traversal; `code` equals `blankCommentBodies(src)` and `blanked` equals
 *   the default `blankLiterals(src)`. This paired mode overrides `keepLiteralText`.
 * @returns {string|{code: string, blanked: string}} each view has the same length as `src`
 */
export function blankLiterals(src, { keepLiteralText = false, includeCommentOnly = false } = {}) {
  return lexSource(src, { keepLiteralText: includeCommentOnly ? false : keepLiteralText, includeCommentOnly });
}

/**
 * Blank COMMENT bodies only, leaving string/template/regex text in place and
 * preserving length. The complement to `blankLiterals`, for a caller that reads
 * a construct's literal TEXT (a log message and the marker emoji in it) and
 * must not be fooled by that same marker appearing in a comment beside it.
 *
 * Shares one lexer with `blankLiterals`, so the two agree by construction about
 * where a comment ends and a literal begins — a second, independent
 * comment-stripper is exactly how a `//` inside a string starts eating code.
 * @param {string} src
 * @returns {string} same length as `src`
 */
export function blankCommentBodies(src) {
  return blankLiterals(src, { keepLiteralText: true });
}

/**
 * Index just PAST the bracket matching the `(`, `[` or `{` at `open`, or -1.
 * Assumes `src` has been through `blankLiterals`, so a bracket inside a string
 * or comment cannot unbalance the walk.
 * @param {string} src
 * @param {number} open
 * @returns {number}
 */
export function matchBracket(src, open) {
  const pairs = { '(': ')', '[': ']', '{': '}' };
  const close = pairs[src[open]];
  if (!close) return -1;
  let depth = 0;
  for (let i = open; i < src.length; i += 1) {
    if (src[i] === src[open]) depth += 1;
    else if (src[i] === close) {
      depth -= 1;
      if (depth === 0) return i + 1;
    }
  }
  return -1;
}

/**
 * Parse the function expression starting at `from` in `blanked` (already through
 * `blankLiterals`), bounded by `limit`. Handles `async`, `function`, and both
 * arrow spellings — parenthesized and bare-identifier parameters.
 *
 * The parameter list is skipped as a UNIT rather than searching for the first
 * `{`, because `async (payload = {}) => {` — the shape half of `sockets/voice.js`
 * uses — puts an object literal in a default value before the body ever opens.
 *
 * A concise arrow body (`async () => save()`) has no braces; everything up to
 * `limit` is taken as the body, so an `await` in it is still seen.
 * @param {string} blanked
 * @param {number} from
 * @param {number} limit - exclusive upper bound (the enclosing call's `)`)
 * @returns {{isAsync: boolean, start: number, text: string}|null} null when the
 *   argument is not a function expression (an identifier reference, say)
 */
export function parseCallbackAt(blanked, from, limit) {
  let i = from;
  const skipSpace = () => { while (i < limit && /\s/.test(blanked[i])) i += 1; };
  skipSpace();

  const isAsync = /^async[\s(]/.test(blanked.slice(i, limit));
  if (isAsync) { i += 'async'.length; skipSpace(); }

  if (blanked.startsWith('function', i)) {
    i += 'function'.length;
    skipSpace();
    // Optional name.
    while (i < limit && /[\w$]/.test(blanked[i])) i += 1;
    skipSpace();
    // Parameter list. Only the `function` spelling reaches this — an arrow's
    // params are consumed below, and skipping a second `(` after its `=>` would
    // step straight over a parenthesized concise body (`async () => (await f())`),
    // hiding every await in it.
    if (blanked[i] === '(') i = matchBracket(blanked, i);
    if (i === -1) return null;
    skipSpace();
  } else {
    // Arrow: parenthesized params, or a single bare identifier.
    if (blanked[i] === '(') i = matchBracket(blanked, i);
    else while (i < limit && /[\w$]/.test(blanked[i])) i += 1;
    if (i === -1) return null;
    skipSpace();
    if (!blanked.startsWith('=>', i)) return null;
    i += 2;
    skipSpace();
  }

  if (blanked[i] === '{') {
    const end = matchBracket(blanked, i);
    if (end === -1) return null;
    return { isAsync, start: i, text: blanked.slice(i, end) };
  }
  return { isAsync, start: i, text: blanked.slice(i, limit) };
}

/**
 * `[start, end)` spans of every `try { … }` block in `body` that actually has a
 * `catch` clause. A `try … finally` with no `catch` runs its cleanup and then
 * re-throws, so it does NOT own the rejection — counting it would let the exact
 * bug these guards exist for through.
 */
function tryBlockSpans(body) {
  const spans = [];
  for (const match of body.matchAll(/\btry\s*\{/g)) {
    const open = body.indexOf('{', match.index);
    const end = matchBracket(body, open);
    // Comments between `}` and `catch` are already blanked to spaces.
    if (end !== -1 && /^\s*catch\b/.test(body.slice(end))) spans.push([open, end]);
  }
  return spans;
}

/**
 * The member/call chain awaited at `start` — e.g. for
 * `await pm2.restart(name)\n  .catch(err => …)` it returns the whole thing,
 * newline continuation included, so a trailing `.catch(` is visible.
 */
function awaitedChain(body, start) {
  let i = start;
  while (i < body.length && /\s/.test(body[i])) i += 1;
  const begin = i;
  while (i < body.length) {
    const c = body[i];
    if (/[\w$.?]/.test(c)) { i += 1; continue; }
    if (c === '(' || c === '[') {
      const end = matchBracket(body, i);
      if (end === -1) break;
      i = end;
      continue;
    }
    if (/\s/.test(c)) {
      // Only a `.` continuation may follow whitespace; anything else ends the chain.
      let j = i;
      while (j < body.length && /\s/.test(body[j])) j += 1;
      if (body[j] === '.') { i = j; continue; }
      break;
    }
    break;
  }
  return body.slice(begin, i);
}

/**
 * True when the LAST link of an awaited chain is `.catch(…)`. It has to be the
 * last one: `await work().catch(recover).then(rethrow)` handles a rejection from
 * `work()` and then hands the awaited promise straight back to `then`, so the
 * chain as a whole can still reject.
 */
function chainEndsInCatch(chain) {
  const at = chain.lastIndexOf('.catch');
  if (at === -1) return false;
  let i = at + '.catch'.length;
  while (i < chain.length && /\s/.test(chain[i])) i += 1;
  if (chain[i] !== '(') return false;
  const end = matchBracket(chain, i);
  return end !== -1 && chain.slice(end).trim() === '';
}

/**
 * Awaits in `body` (already through `blankLiterals`) that neither sit inside a
 * `try`/`catch` nor end in `.catch(…)`. Returns the offending chain text for
 * each, so a failure message points at the expression rather than at a line
 * number that rebases away.
 *
 * Deliberately lexical rather than scope-aware: an `await` inside a nested
 * `async` callback declared within the body is attributed to the body. That
 * errs toward flagging — a fire-and-forget inner async callback has the same
 * ownerless-rejection problem — but it means the fix may belong on the inner
 * function. An await guarded by a helper the body calls, rather than by its own
 * `try`, also reads as unguarded.
 * @param {string} body
 * @returns {string[]}
 */
export function unguardedAwaits(body) {
  const spans = tryBlockSpans(body);
  const offenders = [];
  for (const match of body.matchAll(/\bawait\b/g)) {
    if (spans.some(([from, to]) => match.index > from && match.index < to)) continue;
    const chain = awaitedChain(body, match.index + match[0].length);
    if (chainEndsInCatch(chain)) continue;
    offenders.push(`await ${chain.replace(/\s+/g, ' ').trim()}`);
  }
  return offenders;
}