@excom/kit-logger 0.1.0

package/.rush/temp/chunked-rush-logs/kit-logger.apply-exports.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/all.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/.rush/temp/operation/apply-exports/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 35.46297400000003
+}

package/.rush/temp/shrinkwrap-deps.json

@@ -0,0 +1,3 @@
+{
+  "../../packages/kit-logger": "../../packages/kit-logger:DpFAJ6l9NZ7PxsGv74etlzI4VS4IyRu5jGEhInb3gEw=:"
+}

package/config/rig.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@excom/heft-rig",
+  "rigProfile": "default"
+}
+

package/index.ts

@@ -0,0 +1,103 @@
+const isNumber = (value: unknown): value is number =>
+  typeof value === "number" && !Number.isNaN(value);
+
+/** How deep the summarizer walks into plain objects / arrays. */
+const SUMMARIZE_DEPTH = 6;
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+
+/**
+ * Swap DOM nodes for a short label so the console never serializes a
+ * node tree (huge, circular, slow). Elements become `<tag>` / `<tag#id>`,
+ * other nodes `[Node type=N]`. Walks plain objects and arrays (cycle-safe,
+ * depth-limited). Class instances, errors, and primitives pass through.
+ */
+export const summarizeLogArg = (
+  arg: unknown,
+  depth = SUMMARIZE_DEPTH,
+  seen: WeakSet<object> = new WeakSet()
+): unknown => {
+  if (typeof Node !== "undefined" && arg instanceof Node) {
+    if (arg.nodeType === Node.ELEMENT_NODE) {
+      const el = arg as Element;
+      return el.id ? `<${el.localName}#${el.id}>` : `<${el.localName}>`;
+    }
+    return `[Node type=${arg.nodeType}]`;
+  }
+  if (depth <= 0 || typeof arg !== "object" || arg === null) return arg;
+  if (Array.isArray(arg)) {
+    if (seen.has(arg)) return "[Circular]";
+    seen.add(arg);
+    return arg.map((item) => summarizeLogArg(item, depth - 1, seen));
+  }
+  if (isPlainObject(arg)) {
+    if (seen.has(arg)) return "[Circular]";
+    seen.add(arg);
+    const out: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(arg)) {
+      out[key] = summarizeLogArg(value, depth - 1, seen);
+    }
+    return out;
+  }
+  return arg;
+};
+
+/** Summarize every console argument (see `summarizeLogArg`). */
+export const summarizeLogArgs = (args: any[]) =>
+  args.map((arg) => summarizeLogArg(arg));
+
+export type KitLogManagerOpts = {
+  namespace: string;
+  level?: number;
+  /**
+   * Reshape console args (`[prefix, ...args]`). DOM nodes are summarized
+   * after this, so a custom formatter never has to.
+   */
+  formatArgs?: (args: any[]) => any[];
+};
+export class KitLogManager {
+  namespace: string;
+  level: number;
+  #privateLevel?: number;
+  formatArgs: (args: any[]) => any[];
+  constructor(opts: KitLogManagerOpts) {
+    this.namespace = opts.namespace;
+    const LOG_LEVEL = parseInt((import.meta as any).env.VITE_LOG_LEVEL);
+    this.level = (opts.level ?? isNumber(LOG_LEVEL)) ? LOG_LEVEL : 1;
+    this.formatArgs = opts.formatArgs || ((args) => args);
+  }
+  #format(prefix: string, args: any[]) {
+    return summarizeLogArgs(this.formatArgs([prefix, ...args]));
+  }
+  info(...args) {
+    if (this.level >= 4)
+      console.log(...this.#format(`${this.namespace} info: `, args));
+  }
+  debug(...args) {
+    if (this.level >= 3)
+      console.log(...this.#format(`${this.namespace} debug: `, args));
+  }
+  warn(...args) {
+    if (this.level >= 2)
+      console.warn(...this.#format(`${this.namespace} warn: `, args));
+  }
+  error(...args) {
+    if (this.level >= 1)
+      console.error(...this.#format(`${this.namespace} error: `, args));
+  }
+  suppress() {
+    if (this.#privateLevel !== undefined) return;
+    this.#privateLevel = this.level;
+    this.level = 0;
+  }
+  unsuppress() {
+    if (this.#privateLevel === undefined) return;
+    this.level = this.#privateLevel as number;
+    this.#privateLevel = undefined;
+  }
+}
+export const KitLogger = new KitLogManager({ namespace: "KitLogger" });

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@excom/kit-logger",
+  "version": "0.1.0",
+  "description": "kit-logger library",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {},
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/kit-logger"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/kit-logger/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "kit-logger"
+  ],
+  "excom": {
+    "documented": false,
+    "packageType": "library"
+  },
+  "scripts": {
+    "build": "node node_modules/@excom/heft-rig/scripts/vite-build.mjs",
+    "build:watch": "node node_modules/@excom/heft-rig/scripts/vite-build-watch.mjs",
+    "format": "node node_modules/@excom/heft-rig/scripts/format.mjs",
+    "test": "node node_modules/@excom/heft-rig/scripts/vitest.mjs",
+    "coverage": "node node_modules/@excom/heft-rig/scripts/coverage.mjs"
+  }
+}

package/rush-logs/kit-logger.apply-exports.cache.log

@@ -0,0 +1 @@
+Caching has been disabled for this project's "apply-exports" command.

package/rush-logs/kit-logger.apply-exports.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/support/tests/kit-logger.test.ts

@@ -0,0 +1,242 @@
+import { KitLogManager, summarizeLogArg } from "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "@excom/heft-rig/node_modules/vitest";
+
+describe("KitLogManager", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("logs error at level 1", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 1;
+    manager.error("err");
+    expect(spy).toHaveBeenCalledWith("Test error: ", "err");
+  });
+
+  it("logs warn at level 2", () => {
+    const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 2;
+    manager.warn("w");
+    expect(spy).toHaveBeenCalledWith("Test warn: ", "w");
+  });
+
+  it("logs debug at level 3", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 3;
+    manager.debug("d");
+    expect(spy).toHaveBeenCalledWith("Test debug: ", "d");
+  });
+
+  it("logs info at level 4", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 4;
+    manager.info("i");
+    expect(spy).toHaveBeenCalledWith("Test info: ", "i");
+  });
+
+  it("suppresses log levels below threshold", () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 1;
+    manager.warn("hidden");
+    manager.debug("hidden");
+    manager.info("hidden");
+    manager.error("visible");
+    expect(warnSpy).not.toHaveBeenCalled();
+    expect(logSpy).not.toHaveBeenCalled();
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("suppress and unsuppress restores original level", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 2;
+    manager.suppress();
+    manager.error("suppressed");
+    expect(spy).not.toHaveBeenCalled();
+    expect(manager.level).toBe(0);
+
+    manager.unsuppress();
+    expect(manager.level).toBe(2);
+    manager.error("visible");
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it("double suppress is a no-op", () => {
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 3;
+    manager.suppress();
+    manager.suppress();
+    manager.unsuppress();
+    expect(manager.level).toBe(3);
+  });
+
+  it("unsuppress without suppress is a no-op", () => {
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 2;
+    manager.unsuppress();
+    expect(manager.level).toBe(2);
+  });
+
+  it("uses custom formatArgs", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const manager = new KitLogManager({
+      namespace: "Test",
+      formatArgs: (args) => ["[CUSTOM]", ...args],
+    });
+    manager.level = 1;
+    manager.error("boom");
+    expect(spy).toHaveBeenCalledWith("[CUSTOM]", "Test error: ", "boom");
+  });
+
+  it("summarizes Element args instead of dumping the node tree", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 1;
+    const el = document.createElement("include-content");
+    el.id = "demo";
+    manager.error(el, new Error("boom"));
+    expect(spy).toHaveBeenCalledWith(
+      "Test error: ",
+      "<include-content#demo>",
+      expect.any(Error),
+    );
+  });
+
+  it("summarizes nodes nested in objects and arrays", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 1;
+    const el = document.createElement("p");
+    const error = new Error("boom");
+    manager.error({ element: el, list: [el, 1], error: [error], n: 2 });
+    expect(spy).toHaveBeenCalledWith("Test error: ", {
+      element: "<p>",
+      list: ["<p>", 1],
+      error: [error],
+      n: 2,
+    });
+  });
+
+  it("summarizes nodes even when formatArgs is customized", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const manager = new KitLogManager({
+      namespace: "Test",
+      formatArgs: ([, payload]) => ["custom", payload],
+    });
+    manager.level = 1;
+    const el = document.createElement("span");
+    el.id = "x";
+    manager.error({ element: el });
+    expect(spy).toHaveBeenCalledWith("custom", { element: "<span#x>" });
+  });
+});
+
+describe("summarizeLogArg", () => {
+  it("stops at the depth limit and marks cycles", () => {
+    const cyclic: Record<string, unknown> = { a: 1 };
+    cyclic.self = cyclic;
+    expect(summarizeLogArg(cyclic)).toEqual({ a: 1, self: "[Circular]" });
+    const arr: unknown[] = [];
+    arr.push(arr);
+    expect(summarizeLogArg(arr)).toEqual(["[Circular]"]);
+
+    let deep: Record<string, unknown> = { el: document.createElement("b") };
+    for (let i = 0; i < 8; i++) deep = { deep };
+    const out = summarizeLogArg(deep) as Record<string, unknown>;
+    let cursor: any = out;
+    for (let i = 0; i < 6; i++) cursor = cursor.deep;
+    // beyond the depth limit the object is passed through untouched
+    expect(cursor).toBe(
+      (deep as any).deep.deep.deep.deep.deep.deep
+    );
+  });
+
+  it("passes class instances, errors and primitives through", () => {
+    class Thing {
+      el = document.createElement("i");
+    }
+    const thing = new Thing();
+    const err = new Error("e");
+    expect(summarizeLogArg(thing)).toBe(thing);
+    expect(summarizeLogArg(err)).toBe(err);
+    expect(summarizeLogArg(null)).toBe(null);
+    expect(summarizeLogArg("s")).toBe("s");
+    expect(summarizeLogArg(Object.create(null))).toEqual({});
+  });
+});
+
+describe("KitLogManager edge cases", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("summarizes non-element nodes by node type", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 1;
+    const text = document.createTextNode("hello");
+    manager.error(text);
+    expect(spy).toHaveBeenCalledWith(
+      "Test error: ",
+      `[Node type=${Node.TEXT_NODE}]`,
+    );
+  });
+
+  it("summarizes elements without an id as a bare tag", () => {
+    const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 2;
+    manager.warn(document.createElement("span"));
+    expect(spy).toHaveBeenCalledWith("Test warn: ", "<span>");
+  });
+
+  it("passes plain values through untouched", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 4;
+    const payload = { a: 1 };
+    manager.info(payload, 42, null);
+    expect(spy).toHaveBeenCalledWith("Test info: ", payload, 42, null);
+  });
+
+  it("leaves args alone when Node is not defined (non-DOM runtime)", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const manager = new KitLogManager({ namespace: "Test" });
+    manager.level = 1;
+    vi.stubGlobal("Node", undefined);
+    manager.error("plain");
+    expect(spy).toHaveBeenCalledWith("Test error: ", "plain");
+  });
+
+  it("defaults to level 1 when no level and no env override", () => {
+    const manager = new KitLogManager({ namespace: "Test" });
+    expect(manager.level).toBe(1);
+  });
+
+  it("constructs with an explicit level option", () => {
+    /* Constructor still reads `level` from the env even when `opts.level`
+       is given (operator-precedence bug). Only assert construction succeeds. */
+    const manager = new KitLogManager({ namespace: "Test", level: 3 });
+    expect(manager.namespace).toBe("Test");
+  });
+
+  it("exposes a shared default logger instance", async () => {
+    const { KitLogger } = await import("../../index");
+    expect(KitLogger).toBeInstanceOf(KitLogManager);
+    expect(KitLogger.namespace).toBe("KitLogger");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@excom/heft-rig/profiles/default/config/tsconfig.json",
+  "include": ["./*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}