@weft-js/cli 0.1.1 → 0.1.2

package/src/test-rules/context.mjs

@@ -0,0 +1,109 @@
+import { readFileSync } from 'node:fs'
+import { dirname, relative } from 'node:path'
+import ts from 'typescript'
+import { local } from '../alias.mjs'
+import {
+  assertingFunctions,
+  contains,
+  moduleKey,
+  parse,
+  resolveImport,
+  rootName,
+  unwrap,
+  walk,
+} from './syntax.mjs'
+
+export function importsOf(sf, abs) {
+  const imports = new Map() // local name → { spec, name, abs }
+  const namespaces = new Map() // `import * as x` → spec
+  for (const st of sf.statements) {
+    if (!ts.isImportDeclaration(st) || !st.importClause || !ts.isStringLiteral(st.moduleSpecifier))
+      continue
+    const spec = st.moduleSpecifier.text
+    const target = resolveImport(abs, spec)
+    if (st.importClause.name)
+      imports.set(st.importClause.name.text, { spec, name: 'default', abs: target })
+    const nb = st.importClause.namedBindings
+    if (nb && ts.isNamespaceImport(nb)) namespaces.set(nb.name.text, { spec, abs: target })
+    if (nb && ts.isNamedImports(nb))
+      for (const el of nb.elements)
+        imports.set(el.name.text, { spec, name: (el.propertyName ?? el.name).text, abs: target })
+  }
+  const helperAsserting = new Set()
+  const helperCache = new Map()
+  for (const [binding, imp] of imports) {
+    if (!imp.abs || /\.(test|spec)\./.test(imp.abs)) continue
+    if (!helperCache.has(imp.abs)) {
+      let names = new Set()
+      try {
+        const src = readFileSync(imp.abs, 'utf8')
+        names = assertingFunctions(parse(src, imp.abs))
+      } catch {}
+      helperCache.set(imp.abs, names)
+    }
+    if (helperCache.get(imp.abs).has(imp.name)) helperAsserting.add(binding)
+  }
+  return { imports, namespaces, helperAsserting }
+}
+
+export function unitsOf(sf, abs, imports) {
+  const renders = new Set()
+  walk(sf, (n) => {
+    if (
+      ts.isCallExpression(n) &&
+      ts.isIdentifier(n.expression) &&
+      n.expression.text === 'render' &&
+      n.arguments[0]
+    ) {
+      const first = unwrap(n.arguments[0])
+      if (ts.isIdentifier(first)) renders.add(first.text)
+      walk(first, (j) => {
+        if (
+          (ts.isJsxOpeningElement(j) || ts.isJsxSelfClosingElement(j)) &&
+          ts.isIdentifier(j.tagName)
+        )
+          renders.add(j.tagName.text)
+      })
+    }
+  })
+  const isComponentTest = contains(
+    sf,
+    (n) =>
+      ts.isCallExpression(n) &&
+      ts.isIdentifier(n.expression) &&
+      ['render', 'mount', 'hydrate'].includes(n.expression.text),
+  )
+  const units = new Set()
+  const unitSpecs = new Set()
+  const specKey = (spec) => spec.replace(/(\/index)?\.[cm]?[jt]sx?$/, '')
+  for (const name of renders) {
+    const imp = imports.get(name)
+    if (imp?.abs) units.add(moduleKey(imp.abs))
+    if (imp && local(abs, imp.spec)) unitSpecs.add(specKey(imp.spec))
+  }
+  const own = resolveImport(
+    abs,
+    `./${relative(dirname(abs), abs).replace(/\.(test|spec)\.[cm]?[jt]sx?$/, '')}`,
+  )
+  if (own) units.add(moduleKey(own))
+  const isUnitSpec = (spec) => {
+    const t = resolveImport(abs, spec)
+    return t ? units.has(moduleKey(t)) : unitSpecs.has(specKey(spec))
+  }
+  const isWeftSpec = (spec) =>
+    spec === '@weft-js/core' || spec.startsWith('@weft-js/core/') || spec.startsWith('@weft-js/')
+  return { isComponentTest, isUnitSpec, isWeftSpec }
+}
+
+export function contextOf(sf, abs) {
+  const { imports, namespaces, helperAsserting } = importsOf(sf, abs)
+  const asserting = assertingFunctions(sf, helperAsserting)
+  const { isComponentTest, isUnitSpec, isWeftSpec } = unitsOf(sf, abs, imports)
+  const fakeTimers = contains(
+    sf,
+    (n) =>
+      ts.isPropertyAccessExpression(n) &&
+      (n.name.text === 'useFakeTimers' || (n.name.text === 'install' && rootName(n) === 'clock')),
+  )
+  return { imports, namespaces, asserting, isComponentTest, isUnitSpec, isWeftSpec, fakeTimers }
+}

package/src/test-rules/file-rules.mjs

@@ -0,0 +1,279 @@
+import ts from 'typescript'
+import {
+  contains,
+  hasCall,
+  isLiteral,
+  isSubject,
+  matcherOf,
+  norm,
+  rootName,
+  unwrap,
+  walk,
+} from './syntax.mjs'
+import {
+  flushFix,
+  insideFakeApi,
+  isComparison,
+  readsInternalState,
+  sameValueMatchers,
+  sleepPromise,
+} from './rule-helpers.mjs'
+
+const snapshotMatchers = new Set([
+  'toMatchSnapshot',
+  'toMatchInlineSnapshot',
+  'toMatchFileSnapshot',
+  'toThrowErrorMatchingSnapshot',
+  'toThrowErrorMatchingInlineSnapshot',
+])
+const domQueries = new Set([
+  'querySelector',
+  'querySelectorAll',
+  'getElementsByClassName',
+  'getElementsByTagName',
+  'getElementById',
+  'closest',
+])
+const timerCalls = new Set(['setTimeout', 'setInterval', 'requestAnimationFrame', 'setImmediate'])
+
+export function renderResultsOf(sf, report) {
+  const renderResults = new Set()
+  walk(sf, (n) => {
+    if (
+      ts.isVariableDeclaration(n) &&
+      n.initializer &&
+      ts.isCallExpression(unwrap(n.initializer)) &&
+      rootName(unwrap(n.initializer).expression) === 'render'
+    ) {
+      if (ts.isIdentifier(n.name)) renderResults.add(n.name.text)
+      if (ts.isObjectBindingPattern(n.name))
+        for (const el of n.name.elements)
+          if ((el.propertyName ?? el.name).getText() === 'container')
+            report('T005', el, '`container` reaches into the DOM tree the user never sees.')
+    }
+  })
+  return renderResults
+}
+
+function subjectRule(n, { report }) {
+  if (isSubject(n)) {
+    const m = matcherOf(n)
+    const subject = n.arguments[0]
+    if (m && subject) {
+      if (isLiteral(subject))
+        report('T002', n, `\`${norm(n)}\` checks a literal, so it can never fail.`)
+      else if (
+        sameValueMatchers.has(m.name) &&
+        !m.not &&
+        m.call.arguments[0] &&
+        norm(m.call.arguments[0]) === norm(subject) &&
+        !hasCall(subject)
+      )
+        report(
+          'T002',
+          m.call,
+          `\`${norm(m.call)}\` compares \`${norm(subject)}\` with itself, so it can never fail.`,
+        )
+      else if (
+        ts.isBinaryExpression(unwrap(subject)) &&
+        isComparison(unwrap(subject)) &&
+        norm(unwrap(subject).left) === norm(unwrap(subject).right) &&
+        !hasCall(subject)
+      )
+        report(
+          'T002',
+          n,
+          `\`${norm(subject)}\` compares a value with itself, so it can never fail.`,
+        )
+    }
+  }
+}
+
+function snapshotRule(n, { report }) {
+  if (!isSubject(n)) return
+  const m = matcherOf(n)
+  const subject = n.arguments[0]
+  if (!m || !subject) return
+  if (snapshotMatchers.has(m.name))
+    report(
+      'T007',
+      m.node,
+      `\`${m.name}\` records whatever the code does today and passes against it: it pins output, not behavior.`,
+    )
+}
+
+function subjectDomRule(n, { report, isComponentTest, imports }) {
+  if (!isSubject(n)) return
+  const m = matcherOf(n)
+  const subject = n.arguments[0]
+  if (!m || !subject) return
+  if (m.name === 'toHaveClass')
+    report('T005', m.node, '`toHaveClass` asserts on styling classes, not on what the user sees.')
+  if (
+    contains(
+      subject,
+      (x) =>
+        ts.isPropertyAccessExpression(x) &&
+        ['className', 'classList', 'innerHTML', 'outerHTML'].includes(x.name.text),
+    )
+  ) {
+    const prop = []
+    walk(subject, (x) => {
+      if (
+        ts.isPropertyAccessExpression(x) &&
+        ['className', 'classList', 'innerHTML', 'outerHTML'].includes(x.name.text)
+      )
+        prop.push(x.name.text)
+    })
+    report(
+      'T005',
+      subject,
+      `Asserting on \`${prop[0]}\` pins markup and classes, not what the user sees.`,
+    )
+  }
+  if (isComponentTest && readsInternalState(subject, imports))
+    report(
+      'T005',
+      subject,
+      `\`${norm(subject)}\` reads the component's state directly instead of what it renders.`,
+    )
+}
+
+function queryRule(n, { report }, c, name) {
+  if (name && domQueries.has(name) && ts.isPropertyAccessExpression(c))
+    report('T005', c.name, `\`${name}\` queries by CSS structure, which users never see.`)
+  if (name && /^(get|query|find)(All)?ByTestId$/.test(name))
+    report(
+      'T005',
+      ts.isPropertyAccessExpression(c) ? c.name : c,
+      `\`${name}\` finds the element by a test id the user never sees.`,
+    )
+}
+
+function timerRule(n, { sf, edit, report, fakeTimers }, c, name) {
+  if (name === 'waitFor' || name === 'waitForElementToBeRemoved')
+    report('T004', c, `\`${name}\` polls on real timers and guesses how long the update takes.`, {
+      help: '`await user.click(…)` and `await flush()` settle every update; there is nothing to wait for',
+    })
+  if (ts.isIdentifier(c) && ['sleep', 'delay'].includes(c.text) && ts.isAwaitExpression(n.parent))
+    report(
+      'T004',
+      n,
+      `\`${norm(n)}\` sleeps on the real clock: slow, and flaky when the machine is busy.`,
+    )
+  if (
+    name &&
+    timerCalls.has(name) &&
+    (ts.isIdentifier(c) || ['window', 'globalThis', 'global'].includes(rootName(c)))
+  ) {
+    const sleep = sleepPromise(n)
+    if (sleep) {
+      const delay = n.arguments[1]
+      const zero = !delay || (ts.isNumericLiteral(delay) && Number(delay.text) === 0)
+      const fix = zero ? flushFix(sf, sleep, edit) : undefined
+      report(
+        'T004',
+        sleep,
+        `\`${norm(sleep)}\` sleeps on the real clock: slow, and flaky when the machine is busy.`,
+        {
+          help: zero
+            ? 'Use `await flush()`: it settles every pending update'
+            : `Install the fake clock (\`clock.install()\`) and use \`await clock.advance(${delay.getText()})\``,
+          fix,
+        },
+      )
+    } else if (!fakeTimers && !insideFakeApi(n))
+      report('T004', c, `\`${name}\` runs on the real clock in a test.`, {
+        help: 'Call `clock.install()` from @weft-js/core/test first and drive time with `await clock.advance(ms)`',
+      })
+  }
+}
+
+function mockRule(n, { report, namespaces, isWeftSpec, isUnitSpec }, c, name) {
+  if (
+    name &&
+    ['mock', 'doMock'].includes(name) &&
+    ['vi', 'jest'].includes(rootName(c)) &&
+    n.arguments[0] &&
+    ts.isStringLiteralLike(n.arguments[0])
+  ) {
+    const spec = n.arguments[0].text
+    if (isWeftSpec(spec))
+      report(
+        'T006',
+        n,
+        `Mocking \`${spec}\` replaces the framework the test is supposed to exercise.`,
+      )
+    else if (isUnitSpec(spec))
+      report(
+        'T006',
+        n,
+        `Mocking \`${spec}\` replaces the unit under test, so the test checks the mock.`,
+      )
+  }
+  if (
+    name === 'spyOn' &&
+    ['vi', 'jest'].includes(rootName(c)) &&
+    n.arguments[0] &&
+    ts.isIdentifier(n.arguments[0])
+  ) {
+    const ns = namespaces.get(n.arguments[0].text)
+    if (ns && isWeftSpec(ns.spec))
+      report(
+        'T006',
+        n,
+        `Spying on \`${ns.spec}\` replaces the framework the test is supposed to exercise.`,
+      )
+    else if (ns && isUnitSpec(ns.spec))
+      report(
+        'T006',
+        n,
+        `Spying on \`${ns.spec}\` replaces the unit under test, so the test checks the mock.`,
+      )
+  }
+}
+
+function domRule(n, ctx, c, name) {
+  subjectDomRule(n, ctx)
+  queryRule(n, ctx, c, name)
+}
+
+const callRules = [subjectRule, snapshotRule, domRule, timerRule, mockRule]
+
+function callRule(n, ctx) {
+  if (!ts.isCallExpression(n)) return
+  const c = n.expression
+  const name = ts.isIdentifier(c)
+    ? c.text
+    : ts.isPropertyAccessExpression(c)
+      ? c.name.text
+      : undefined
+  for (const rule of callRules) rule(n, ctx, c, name)
+}
+
+function socketRule(n, { report }) {
+  if (
+    ts.isNewExpression(n) &&
+    ts.isIdentifier(n.expression) &&
+    ['WebSocket', 'EventSource'].includes(n.expression.text)
+  )
+    report('T013', n, `\`new ${n.expression.text}\` opens a real socket in a fast test.`, {
+      help: "Render the `.live()` or stream against @weft-js/core/test's fake transport: `await net.push(stream, message)`, `await net.poke('tag')`, `await net.drop()`",
+    })
+}
+
+function containerRule(n, { report, renderResults }) {
+  if (
+    ts.isPropertyAccessExpression(n) &&
+    n.name.text === 'container' &&
+    !(ts.isCallExpression(n.parent) && n.parent.expression === n)
+  ) {
+    const obj = unwrap(n.expression)
+    const fromRender =
+      (ts.isCallExpression(obj) && rootName(obj.expression) === 'render') ||
+      (ts.isIdentifier(obj) && renderResults.has(obj.text))
+    if (fromRender) report('T005', n, '`container` reaches into the DOM tree the user never sees.')
+  }
+}
+
+export const fileRules = [callRule, socketRule, containerRule]

package/src/test-rules/rule-helpers.mjs

@@ -0,0 +1,244 @@
+import ts from 'typescript'
+import {
+  contains,
+  hasCall,
+  isFn,
+  isLiteral,
+  isSubject,
+  matcherOf,
+  norm,
+  unwrap,
+} from './syntax.mjs'
+
+export const sameValueMatchers = new Set(['toBe', 'toEqual', 'toStrictEqual'])
+const loopCallbacks = new Set([
+  'forEach',
+  'map',
+  'flatMap',
+  'filter',
+  'some',
+  'every',
+  'find',
+  'findIndex',
+  'reduce',
+])
+export const isComparison = (b) =>
+  [
+    ts.SyntaxKind.EqualsEqualsEqualsToken,
+    ts.SyntaxKind.EqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsToken,
+  ].includes(b.operatorToken.kind)
+
+/** Why `node`, under ancestor `a`, only runs sometimes (`loop`: maybe zero times); undefined when it always runs. */
+export function conditional(a, node) {
+  const within = (x) => x && node.getStart() >= x.getStart() && node.getEnd() <= x.getEnd()
+  const when = (text) => ({ text })
+  const loop = (text) => ({ text, loop: true })
+  if (ts.isIfStatement(a) && !within(a.expression)) return when('when the `if` matches')
+  if (ts.isConditionalExpression(a) && !within(a.condition)) return when('on one side of a `?:`')
+  if (
+    ts.isBinaryExpression(a) &&
+    [
+      ts.SyntaxKind.AmpersandAmpersandToken,
+      ts.SyntaxKind.BarBarToken,
+      ts.SyntaxKind.QuestionQuestionToken,
+    ].includes(a.operatorToken.kind) &&
+    within(a.right)
+  )
+    return when(`after a \`${a.operatorToken.getText()}\``)
+  if (ts.isCaseClause(a) || ts.isDefaultClause(a)) return when('in one `switch` case')
+  if (ts.isCatchClause(a)) return when('when something throws')
+  if (
+    (ts.isForStatement(a) ||
+      ts.isForOfStatement(a) ||
+      ts.isForInStatement(a) ||
+      ts.isWhileStatement(a) ||
+      ts.isDoStatement(a)) &&
+    within(a.statement)
+  )
+    return loop('inside a loop, and zero iterations check nothing')
+  if (
+    isFn(a) &&
+    ts.isCallExpression(a.parent) &&
+    ts.isPropertyAccessExpression(a.parent.expression) &&
+    loopCallbacks.has(a.parent.expression.name.text) &&
+    a.parent.arguments.includes(a)
+  )
+    return loop(`inside \`.${a.parent.expression.name.text}\`, and an empty list checks nothing`)
+  return undefined
+}
+
+/** `expect(cart.items.value)` with `cart` imported from app code, in a component test. (`scope(cart)` from @weft-js/core/test is the way to test a scope.) */
+export function readsInternalState(subject, imports) {
+  const s = unwrap(subject)
+  if (!ts.isPropertyAccessExpression(s) || s.name.text !== 'value') return false
+  let n = s.expression
+  for (;;) {
+    n = unwrap(n)
+    if (ts.isPropertyAccessExpression(n) || ts.isElementAccessExpression(n)) n = n.expression
+    else break
+  }
+  return ts.isIdentifier(n) && Boolean(imports.get(n.text)?.abs)
+}
+
+/** `new Promise(r => setTimeout(r, ms))`: the timer call's enclosing sleep, or undefined. */
+export function sleepPromise(timer) {
+  const cb = timer.arguments[0]
+  let exec = timer.parent
+  while (exec && (ts.isExpressionStatement(exec) || ts.isBlock(exec))) exec = exec.parent
+  if (
+    !isFn(exec) ||
+    !ts.isNewExpression(exec.parent) ||
+    exec.parent.expression.getText() !== 'Promise'
+  )
+    return undefined
+  const resolveName = exec.parameters[0]?.name.getText()
+  const callsResolve =
+    cb &&
+    (cb.getText() === resolveName ||
+      (isFn(cb) &&
+        contains(cb.body, (x) => ts.isCallExpression(x) && x.expression.getText() === resolveName)))
+  if (!callsResolve) return undefined
+  // A fake API's latency resolves with data (`ok(user)`); a sleep resolves with nothing.
+  if (
+    isFn(cb) &&
+    contains(
+      cb.body,
+      (x) =>
+        ts.isCallExpression(x) && x.expression.getText() === resolveName && x.arguments.length > 0,
+    )
+  )
+    return undefined
+  return exec.parent
+}
+
+/** Timers inside a function that a fake API returns (`load: id => new Promise(ok => setTimeout(() => ok(x), ms))`). */
+export function insideFakeApi(timer) {
+  for (let n = timer.parent; n; n = n.parent) {
+    if (ts.isNewExpression(n) && n.expression.getText() === 'Promise') return true
+  }
+  return false
+}
+
+/** Replace a zero-delay sleep with `flush()`, importing it from @weft-js/core/test when the file doesn't. */
+export function flushFix(sf, sleep, edit) {
+  const edits = [edit(sleep.getStart(sf), sleep.getEnd(), 'flush()')]
+  const hasFlush = sf.statements.some(
+    (st) =>
+      ts.isImportDeclaration(st) &&
+      st.importClause?.namedBindings &&
+      ts.isNamedImports(st.importClause.namedBindings) &&
+      st.importClause.namedBindings.elements.some((e) => e.name.text === 'flush'),
+  )
+  if (!hasFlush) {
+    const weftTest = sf.statements.find(
+      (st) =>
+        ts.isImportDeclaration(st) &&
+        ts.isStringLiteral(st.moduleSpecifier) &&
+        st.moduleSpecifier.text === '@weft-js/core/test' &&
+        st.importClause?.namedBindings &&
+        ts.isNamedImports(st.importClause.namedBindings),
+    )
+    if (weftTest) {
+      const el = weftTest.importClause.namedBindings.elements
+      edits.push(edit(el[el.length - 1].getEnd(), el[el.length - 1].getEnd(), ', flush'))
+    } else {
+      const last = [...sf.statements].reverse().find((st) => ts.isImportDeclaration(st))
+      const at = last ? last.getEnd() : 0
+      edits.push(
+        edit(
+          at,
+          at,
+          `${last ? '\n' : ''}import { flush } from '@weft-js/core/test'${last ? '' : '\n'}`,
+        ),
+      )
+    }
+  }
+  return { description: 'Replace the sleep with `flush()`', safe: false, edits }
+}
+
+/**
+ * T003 in one test body: `n.value = 5; expect(n.value).toBe(5)`, or `const s = state(3); expect(s.value).toBe(3)`.
+ * Any call between the write and the assertion (a click, a render, a fake push) may route through the app, so it ends
+ * the check; `flush()` doesn't.
+ */
+export function assertsWhatItSet(statements, report) {
+  const writes = new Map()
+  const boxes = new Set() // `const n = state(…)`: a plain box, so a write reads straight back
+  const locals = new Set()
+  const isFlush = (st) => {
+    const e = ts.isExpressionStatement(st) ? unwrap(st.expression) : null
+    return e && ts.isCallExpression(e) && e.expression.getText() === 'flush'
+  }
+  for (const st of statements) {
+    if (ts.isVariableStatement(st)) {
+      for (const d of st.declarationList.declarations) {
+        if (!ts.isIdentifier(d.name) || !d.initializer) continue
+        const init = unwrap(d.initializer)
+        locals.add(d.name.text)
+        if (ts.isCallExpression(init) && init.expression.getText() === 'state')
+          boxes.add(d.name.text)
+        if (isLiteral(init)) writes.set(d.name.text, init)
+        else if (
+          ts.isCallExpression(init) &&
+          init.expression.getText() === 'state' &&
+          init.arguments[0] &&
+          isLiteral(init.arguments[0])
+        )
+          writes.set(`${d.name.text}.value`, init.arguments[0])
+        else if (hasCall(init)) writes.clear()
+      }
+      continue
+    }
+    if (isFlush(st)) continue
+    const e = ts.isExpressionStatement(st) ? unwrap(st.expression) : null
+    if (
+      e &&
+      ts.isBinaryExpression(e) &&
+      e.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+      !hasCall(e.left)
+    ) {
+      const target = norm(e.left)
+      const plain =
+        (ts.isIdentifier(e.left) && locals.has(target)) ||
+        (ts.isPropertyAccessExpression(e.left) &&
+          e.left.name.text === 'value' &&
+          boxes.has(norm(e.left.expression)))
+      if (isLiteral(e.right) && plain) writes.set(target, e.right)
+      else writes.delete(target)
+      if (hasCall(e.right)) writes.clear()
+      continue
+    }
+    const subject = e && findSubject(e)
+    if (subject) {
+      const m = matcherOf(subject)
+      const written = subject.arguments[0] && writes.get(norm(subject.arguments[0]))
+      if (
+        m &&
+        !m.not &&
+        sameValueMatchers.has(m.name) &&
+        written &&
+        m.call.arguments[0] &&
+        norm(m.call.arguments[0]) === norm(written)
+      )
+        report(
+          'T003',
+          m.call,
+          `The test set \`${norm(subject.arguments[0])}\` to \`${norm(written)}\` itself and asserts it back: nothing between went through the UI or the graph.`,
+        )
+      continue
+    }
+    writes.clear()
+  }
+}
+
+/** The subject call of a statement that is one assertion chain (`expect(a).toBe(b)`), else undefined. */
+function findSubject(e) {
+  let n = unwrap(e)
+  for (;;) {
+    if (ts.isCallExpression(n) && isSubject(n)) return n
+    if (ts.isCallExpression(n) || ts.isPropertyAccessExpression(n)) n = unwrap(n.expression)
+    else return undefined
+  }
+}