@appium/docutils 0.3.4 → 0.3.5

package/lib/logger.ts

@@ -136,58 +136,59 @@ class DocutilsReporter extends FancyReporter {
  */
 let globalLevel: LogLevel = LogLevelMap[DEFAULT_LOG_LEVEL];
 
+/**
+ * Type guard to see if a string is a recognized log level
+ * @param level any value
+ */
+export function isLogLevelString(level: any): level is keyof typeof LogLevelMap {
+  return level in LogLevelMap;
+}
+
 /**
  * The logger from which all loggers are created.  This one uses a unique tag and our custom reporter.
  */
-const rootLogger = createLogProxy(
-  consola.create({defaults: {tag: 'docutils'}, reporters: [new DocutilsReporter()]})
-);
+const rootLogger = consola.create({
+  defaults: {tag: 'docutils'},
+  reporters: [new DocutilsReporter()],
+  level: globalLevel,
+});
+// this prevents logging before `initLogger` is called
+rootLogger.pause();
 
 /**
- * @summary Creates a log-level-propagating proxy for a {@linkcode Consola} logger.
- * @description
- * Alright.  So when you create a new logger via {@linkcode Consola.create}, it's basically a clone
- * of its parent with a new set of options.
- *
- * If we change the log level of the root logger (which we do: see `cli/index.ts`), we may (almost
- * certainly) have
- * child loggers which: a) have already been created and b) have inherited the old/default log level
- * from the root logger. We don't _want_ that (though this is likely a reasonable use case) for our
- * purposes.
- *
- * The implementation below solves the problem by maintaining its own singleton log level value, and
- * intercepts the `level` property of any logger created from the root logger.
- *
- * There are other ways to go about this which may be better, but this seemed pretty straightforward.
+ * A map of tags to loggers
  */
-function createLogProxy(logger: Consola): Consola {
-  return new Proxy(logger, {
-    get(target, prop, receiver) {
-      if (prop === 'level') {
-        return globalLevel;
-      }
-      if (prop === 'create') {
-        const create = Reflect.get(target, prop, receiver) as Consola['create'];
-        return (opts: ConsolaOptions) => createLogProxy(create.call(receiver, opts));
-      }
-      if (prop === '_defaults') {
-        const defaults = Reflect.get(target, prop, receiver);
-        return {...defaults, level: globalLevel};
-      }
-      return Reflect.get(target, prop, receiver);
-    },
-    set(target, prop, value, receiver) {
-      if (prop === 'level') {
-        globalLevel = value as LogLevel;
-        return true;
-      }
-      return Reflect.set(target, prop, value, receiver);
-    },
-  });
+const loggers: Map<string, WeakRef<Consola>> = new Map();
+
+export function getLogger(tag: string, parent = rootLogger) {
+  if (loggers.has(tag)) {
+    const logger = loggers.get(tag)?.deref();
+    if (logger) {
+      return logger;
+    }
+  }
+  const logger = parent.withTag(tag);
+  logger.level = globalLevel;
+  loggers.set(tag, new WeakRef(logger));
+  return logger;
 }
 
 /**
- * The proxied root logger
- * @see {createLogProxy}
+ * Initialize the logging system.
+ *
+ * This should only be called once. The loglevel cannot be changed once it is set.
+ *
+ * @remarks Child loggers seem to inherit the "paused" state of the parent, so when this is called, we must resume all of them.
  */
-export default rootLogger;
+export const initLogger = _.once((level: keyof typeof LogLevelMap | LogLevel) => {
+  globalLevel = isLogLevelString(level) ? LogLevelMap[level] : level;
+  rootLogger.level = globalLevel;
+  rootLogger.resume();
+  for (const ref of loggers.values()) {
+    const logger = ref.deref();
+    if (logger) {
+      logger.level = globalLevel;
+      logger.resume();
+    }
+  }
+});

package/lib/scaffold.ts

@@ -4,7 +4,7 @@
  */
 
 import {fs} from '@appium/support';
-import logger from './logger';
+import {getLogger} from './logger';
 import path from 'node:path';
 import {createPatch} from 'diff';
 import {NormalizedPackageJson} from 'read-pkg';
@@ -15,8 +15,8 @@ import _ from 'lodash';
 import {stringifyJson, readPackageJson, safeWriteFile} from './fs';
 import {NAME_ERR_ENOENT, NAME_ERR_EEXIST} from './constants';
 
-const log = logger.withTag('init');
-const dryRunLog = log.withTag('dry-run');
+const log = getLogger('init');
+const dryRunLog = getLogger('dry-run', log);
 
 /**
  * Creates a unified patch for display in "dry run" mode

package/lib/validate.ts

@@ -40,7 +40,7 @@ import {
   whichPython,
   readMkDocsYml,
 } from './fs';
-import logger from './logger';
+import {getLogger} from './logger';
 import {MkDocsYml, PipPackage, TypeDocJson} from './model';
 import {relative} from './util';
 
@@ -64,7 +64,7 @@ const TYPEDOC_VERSION_REGEX = /TypeDoc\s(\d+\.\d+\..+)/;
  */
 const MKDOCS_VERSION_REGEX = /mkdocs,\s+version\s+(\d+\.\d+\.\S+)/;
 
-const log = logger.withTag('validate');
+const log = getLogger('validate');
 
 /**
  * The "kinds" of validation which were requested to be performed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/docutils",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Documentation generation utilities for Appium and related projects",
   "keywords": [
     "automation",
@@ -49,9 +49,9 @@
     "start": "node ./build/lib/cli/index.js"
   },
   "dependencies": {
-    "@appium/support": "^3.1.9",
-    "@appium/tsconfig": "^0.2.4",
-    "@appium/typedoc-plugin-appium": "^0.6.0",
+    "@appium/support": "^3.1.10",
+    "@appium/tsconfig": "^0.3.0",
+    "@appium/typedoc-plugin-appium": "^0.6.1",
     "@sliphua/lilconfig-ts-loader": "3.2.2",
     "chalk": "4.1.2",
     "consola": "2.15.3",
@@ -67,7 +67,7 @@
     "semver": "7.3.8",
     "source-map-support": "0.5.21",
     "teen_process": "2.0.2",
-    "type-fest": "3.7.2",
+    "type-fest": "3.8.0",
     "typedoc": "0.23.28",
     "typedoc-plugin-markdown": "3.14.0",
     "typedoc-plugin-resolve-crossmodule-references": "0.3.3",
@@ -83,5 +83,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "591d15bc5e65383f824fc8eaa5f2814266a34df4"
+  "gitHead": "e9b50225dc09a306b6eb8dafa0543c2a45cb8238"
 }

package/requirements.txt

@@ -1,4 +1,4 @@
 mkdocs==1.4.2
-mkdocs-material==9.1.5
+mkdocs-material==9.1.6
 mkdocs-material-extensions==1.1.1
 mike==1.1.2