@naturalcycles/dev-lib 20.69.0 → 20.71.0

package/cfg/oxlint-plugin-nc.d.ts

@@ -0,0 +1,10 @@
+import type { RuleTester } from 'oxlint/plugins-dev'
+
+type Rule = Parameters<RuleTester['run']>[1]
+
+declare const ncPlugin: {
+  meta: { name: string }
+  rules: { 'prefer-assert': Rule }
+}
+
+export default ncPlugin

package/cfg/oxlint-plugin-nc.js

@@ -0,0 +1,148 @@
+const ASSERTABLE_ERRORS = new Set(['Error', 'AppError', 'AssertionError'])
+const EQUALITY_OPERATORS = new Set(['===', '!==', '==', '!='])
+// A condition that stays readable once negated; `!(a instanceof B && c)` does not
+const UNASSERTABLE_TESTS = new Set([
+  'LogicalExpression',
+  'ConditionalExpression',
+  'AssignmentExpression',
+  'SequenceExpression',
+])
+// An inline callback in the condition (`items.some(item => ...)`) does not read as an assertion once negated
+const FUNCTION_NODES = new Set(['ArrowFunctionExpression', 'FunctionExpression'])
+// `_assert` builds its message and data before checking, so a call, await or interpolated message there
+// would run on the happy path too (keep ids in the data bag), and a value the condition narrows
+// (`if (!res.ok) throw new Error(res.error)`) no longer typechecks
+const EVALUATED_ARGUMENTS = new Set([
+  'CallExpression',
+  'NewExpression',
+  'AwaitExpression',
+  'TaggedTemplateExpression',
+  'YieldExpression',
+  'UpdateExpression',
+  'AssignmentExpression',
+  'SpreadElement',
+])
+// Test files and test helpers throw plain errors on purpose (mocks, fakes). Checked here rather than in
+// a shared `overrides` entry, because `defineOxlintConfig` lets a consumer's `overrides` replace it
+const TEST_FILE_PATTERN = /\.(?:test|spec)\.[cm]?[jt]sx?$|\/(?:test|testing)\//
+
+// No `fix`/`suggest`: dev-lib runs oxlint with --fix-dangerously, which would apply them and leave
+// `_assert` unimported
+const preferAssertRule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Prefer _assert over an if whose only statement throws an Error or AppError with a static message',
+    },
+    messages: {
+      preferAssert:
+        'Use _assert(condition, message, data) from @naturalcycles/js-lib/error instead of throwing in an if',
+    },
+  },
+  create(context) {
+    if (TEST_FILE_PATTERN.test(context.filename)) return {}
+
+    return {
+      IfStatement(node) {
+        if (node.alternate || node.parent.type === 'IfStatement') return
+        if (!isAssertableTest(node.test)) return
+
+        const { consequent } = node
+        const statement =
+          consequent.type === 'BlockStatement' && consequent.body.length === 1
+            ? consequent.body[0]
+            : consequent
+        if (statement?.type !== 'ThrowStatement') return
+
+        const error = statement.argument
+        if (
+          error.type !== 'NewExpression' ||
+          error.callee.type !== 'Identifier' ||
+          !ASSERTABLE_ERRORS.has(error.callee.name) ||
+          error.arguments.length > maxArguments(error.callee.name) ||
+          error.arguments.some(argument => containsEvaluation(argument))
+        ) {
+          return
+        }
+        const narrowed = referencedNames(node.test)
+        if (error.arguments.some(argument => referencesAny(argument, narrowed))) return
+
+        context.report({ node, messageId: 'preferAssert' })
+      },
+    }
+  },
+}
+
+// A second `Error` argument is `{ cause }`, which `_assert` would store as data and lose as a cause
+function maxArguments(errorName) {
+  return errorName === 'Error' ? 1 : 2
+}
+
+function isAssertableTest(test) {
+  if (UNASSERTABLE_TESTS.has(test.type)) return false
+  if (test.type === 'BinaryExpression' && !EQUALITY_OPERATORS.has(test.operator)) return false
+  return !containsFunction(test)
+}
+
+function containsFunction(node) {
+  return visit(node, child => FUNCTION_NODES.has(child.type))
+}
+
+function containsEvaluation(node) {
+  return visit(
+    node,
+    child =>
+      EVALUATED_ARGUMENTS.has(child.type) ||
+      (child.type === 'TemplateLiteral' && child.expressions.length > 0),
+  )
+}
+
+function referencedNames(node) {
+  const names = new Set()
+  visit(node, child => {
+    if (child.type === 'Identifier') names.add(child.name)
+    if (child.type === 'ThisExpression') names.add('this')
+    return false
+  })
+  return names
+}
+
+function referencesAny(node, names) {
+  return visit(node, child => {
+    if (child.type === 'Identifier') return names.has(child.name)
+    if (child.type === 'ThisExpression') return names.has('this')
+    return false
+  })
+}
+
+/**
+ * Depth-first walk over the AST below `node`, skipping `parent` links and the names that are not
+ * references: non-computed member properties and object keys. Stops at the first node `fn` returns
+ * true for, and returns whether there was one.
+ */
+function visit(node, fn) {
+  if (!node || typeof node !== 'object') return false
+  if (Array.isArray(node)) return node.some(item => visit(item, fn))
+  const { type } = node
+  if (!type) return false
+  if (fn(node)) return true
+  for (const [key, child] of Object.entries(node)) {
+    if (key === 'parent' || key === 'loc' || key === 'range') continue
+    if (key === 'property' && type === 'MemberExpression' && !node.computed) continue
+    if (key === 'key' && type === 'Property' && !node.computed) continue
+    if (visit(child, fn)) return true
+  }
+  return false
+}
+
+const ncPlugin = {
+  meta: {
+    name: 'nc',
+  },
+  rules: {
+    'prefer-assert': preferAssertRule,
+  },
+}
+
+export default ncPlugin

package/cfg/oxlint.config.js

@@ -39,7 +39,10 @@ export const sharedConfig = {
     // "vue",
     'vitest',
   ],
-  jsPlugins: [`${import.meta.dirname}/oxlint-plugin-stylistic.js`],
+  jsPlugins: [
+    `${import.meta.dirname}/oxlint-plugin-stylistic.js`,
+    `${import.meta.dirname}/oxlint-plugin-nc.js`,
+  ],
   options: {
     reportUnusedDisableDirectives: 'deny',
     respectEslintDisableDirectives: false,
@@ -69,6 +72,7 @@ export const sharedConfig = {
       { blankLine: 'always', prev: '*', next: 'class' },
     ],
     '@stylistic/lines-between-class-members': [2, 'always', { exceptAfterSingleLine: true }],
+    'nc/prefer-assert': 2,
     complexity: [2, { max: 40 }],
     'logical-assignment-operators': [
       2,
@@ -92,8 +96,10 @@ export const sharedConfig = {
     'object-shorthand': 2,
     'valid-expect': 0,
     'valid-title': 0,
-    'vitest/valid-title': 0,
+    'vitest/valid-title': [2, { mustMatch: { it: '^should ' } }],
     'valid-describe-callback': 0,
+    // Options arguments and variables are `opt`, never `opts`
+    'id-denylist': [2, 'opts'],
     // 'id-denylist': [
     //   0, // actually not useful
     //   'any',
@@ -142,6 +148,7 @@ export const sharedConfig = {
         name: 'Intl',
         message: 'Use Intl2 instead.',
       },
+      { name: 'Date', message: 'Use localTime / localDate from @naturalcycles/js-lib/datetime.' },
     ],
     'no-unused-expressions': 2,
     'no-var': 2,
@@ -458,13 +465,7 @@ export const sharedConfig = {
     'vitest/prefer-called-exactly-once-with': 2,
     'vitest/consistent-test-filename': 2,
     'vitest/warn-todo': 0,
-    'vitest/consistent-test-it': [
-      2,
-      {
-        fn: 'test',
-        withinDescribe: 'test',
-      },
-    ],
+    'vitest/consistent-test-it': [2, { fn: 'it', withinDescribe: 'it' }],
     'vitest/max-nested-describe': [0, { max: 4 }], // not good
     'vitest/no-alias-methods': 2,
     'vitest/no-restricted-vi-methods': [

package/dist/check.util.js

@@ -4,6 +4,7 @@ import { findPackageJSON } from 'node:module';
 import path from 'node:path';
 import { _isTruthy } from '@naturalcycles/js-lib';
 import { _uniq } from '@naturalcycles/js-lib/array';
+import { nowUnixMillis } from '@naturalcycles/js-lib/datetime/localTime.js';
 import { _since } from '@naturalcycles/js-lib/datetime/time.util.js';
 import { _assert } from '@naturalcycles/js-lib/error/assert.js';
 import { _filterFalsyValues } from '@naturalcycles/js-lib/object/object.util.js';
@@ -24,7 +25,7 @@ const { CI } = process.env;
  */
 export async function runCheck(opt = {}) {
     const { fastLinters = true, eslint = true, stylelint = true, oxfmt = true, ktlint = true, typecheck = false, test = true, } = opt;
-    const started = Date.now();
+    const started = nowUnixMillis();
     let s;
     const timings = {};
     // const { commitOnChanges, failOnChanges } = _yargs().options({
@@ -49,52 +50,52 @@ export async function runCheck(opt = {}) {
     const fix = !CI;
     if (fastLinters) {
         // Fast linters (that run in <1 second) go first
-        s = Date.now();
+        s = nowUnixMillis();
         if (runActionLint()) {
-            timings['actionlint'] = Date.now() - s;
+            timings['actionlint'] = nowUnixMillis() - s;
         }
-        s = Date.now();
+        s = nowUnixMillis();
         if (runOxlint(fix)) {
-            timings['oxlint'] = Date.now() - s;
+            timings['oxlint'] = nowUnixMillis() - s;
         }
     }
     // From this point we start the "slow" linters, with ESLint leading the way
     if (eslint) {
         // We run eslint BEFORE Prettier, because eslint can delete e.g unused imports.
-        s = Date.now();
+        s = nowUnixMillis();
         if (eslintAll({ fix })) {
-            timings['eslint'] = Date.now() - s;
+            timings['eslint'] = nowUnixMillis() - s;
         }
     }
     if (stylelint &&
         hasDependencyInNodeModules('stylelint') &&
         hasDependencyInNodeModules('stylelint-config-standard-scss')) {
-        s = Date.now();
+        s = nowUnixMillis();
         if (stylelintAll(fix)) {
-            timings['stylelint'] = Date.now() - s;
+            timings['stylelint'] = nowUnixMillis() - s;
         }
     }
     if (oxfmt) {
-        s = Date.now();
+        s = nowUnixMillis();
         if (runOxfmt(fix)) {
-            timings['oxfmt'] = Date.now() - s;
+            timings['oxfmt'] = nowUnixMillis() - s;
         }
     }
     if (ktlint) {
-        s = Date.now();
+        s = nowUnixMillis();
         if (await runKTLint(fix)) {
-            timings['ktlint'] = Date.now() - s;
+            timings['ktlint'] = nowUnixMillis() - s;
         }
     }
     if (typecheck) {
-        s = Date.now();
+        s = nowUnixMillis();
         await runTypecheck();
-        timings['tsc'] = Date.now() - s;
+        timings['tsc'] = nowUnixMillis() - s;
     }
     if (test) {
-        s = Date.now();
+        s = nowUnixMillis();
         if (runTest()) {
-            timings['test'] = Date.now() - s;
+            timings['test'] = nowUnixMillis() - s;
         }
     }
     console.log(`${check(true)}${white(`check`)} ${dimGrey(`took ` + _since(started))}`);

package/dist/release/notes.util.js

@@ -1,3 +1,4 @@
+import { localDate } from '@naturalcycles/js-lib/datetime/localDate.js';
 /**
  * Generate release notes markdown for a GitHub Release,
  * following the format of `@semantic-release/release-notes-generator` (angular preset):
@@ -5,7 +6,7 @@
  */
 export function generateReleaseNotes(input) {
     const { repo, commits, lastTag, nextTag } = input;
-    const date = input.date || new Date().toISOString().slice(0, 10);
+    const date = input.date || localDate.todayInUTC().toISODate();
     const header = lastTag
         ? `## [${nextTag}](${repo.url}/compare/${lastTag}...${nextTag}) (${date})`
         : `## ${nextTag} (${date})`;

package/dist/testing/mockAllKindsOfThings.js

@@ -44,6 +44,7 @@ export const mockAllKindsOfThings = () => {
             k1: 'v1',
         }),
         Symbol('a_am_symbol'),
+        // oxlint-disable-next-line no-restricted-globals -- a native Date is one of the kinds of things
         new Date(1984, 5, 21),
     ];
 };

package/dist/vendor/mitm.d.ts

@@ -11,7 +11,7 @@ export interface BypassableSocket extends NetType.Socket {
     bypass: () => void;
     bypassed?: boolean;
 }
-export type ConnectCallback = (socket: BypassableSocket, opts: SocketOptions) => void;
+export type ConnectCallback = (socket: BypassableSocket, opt: SocketOptions) => void;
 export interface Mitm {
     on: (event: 'connect', callback: ConnectCallback) => void;
     disable: () => void;

package/dist/vendor/mitm.js

@@ -18,7 +18,7 @@ export function createMitm() {
             s[0][s[1]] = s[2];
         }
     }
-    function connect(orig, opts, done) {
+    function connect(orig, opt, done) {
         // Create a bypassable socket that we'll pass to listeners
         const socket = new Net.Socket();
         socket.bypassed = false;
@@ -27,11 +27,11 @@ export function createMitm() {
         };
         // Emit connect event to all listeners
         for (const listener of listeners) {
-            listener(socket, opts);
+            listener(socket, opt);
         }
         // If bypassed, call the original connect function
         if (socket.bypassed) {
-            return orig.call(Net, opts, done);
+            return orig.call(Net, opt, done);
         }
         // Not bypassed - return the socket that will never actually connect.
         // testOffline throws an error before we get here, so this is just a fallback.
@@ -43,12 +43,12 @@ export function createMitm() {
         // connect(options, callback?)
         // connect(path, callback?) - Unix socket
         if (typeof args[0] === 'number') {
-            const opts = { port: args[0] };
+            const opt = { port: args[0] };
             if (typeof args[1] === 'string') {
-                opts.host = args[1];
-                return [opts, args[2]];
+                opt.host = args[1];
+                return [opt, args[2]];
             }
-            return [opts, args[1]];
+            return [opt, args[1]];
         }
         if (typeof args[0] === 'object' && args[0] !== null) {
             return [args[0], args[1]];
@@ -58,14 +58,14 @@ export function createMitm() {
     }
     function createNetConnect(orig) {
         return function (...args) {
-            const [opts, done] = normalizeArgs(args);
-            return connect(orig, opts, done);
+            const [opt, done] = normalizeArgs(args);
+            return connect(orig, opt, done);
         };
     }
     function createTlsConnect(orig) {
         return function (...args) {
-            const [opts, done] = normalizeArgs(args);
-            return connect(orig, opts, done);
+            const [opt, done] = normalizeArgs(args);
+            return connect(orig, opt, done);
         };
     }
     // Stub network functions

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/dev-lib",
   "type": "module",
-  "version": "20.69.0",
+  "version": "20.71.0",
   "dependencies": {
     "prompts": "^2",
     "@naturalcycles/js-lib": "^15",