@superblocksteam/sdk 2.0.150-next.0 → 2.0.150-next.2

package/src/cli-replacement/npm-install-timing.test.mts

@@ -0,0 +1,199 @@
+import nodeFs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { consumeNpmInstallTimingAttributes } from "./npm-install-timing.mjs";
+
+let logsDir: string;
+
+beforeEach(async () => {
+  logsDir = await nodeFs.mkdtemp(path.join(os.tmpdir(), "npm-timing-"));
+});
+
+afterEach(async () => {
+  await nodeFs.rm(logsDir, { force: true, recursive: true });
+});
+
+/** Write a timing file using npm's own naming (`<log id>-timing.json`). */
+async function writeTimingFile(
+  logId: string,
+  contents: unknown,
+): Promise<string> {
+  const file = path.join(logsDir, `${logId}-timing.json`);
+  await nodeFs.writeFile(
+    file,
+    typeof contents === "string" ? contents : JSON.stringify(contents),
+  );
+  return file;
+}
+
+async function listTimingFiles(): Promise<string[]> {
+  const entries = await nodeFs.readdir(logsDir);
+  return entries.filter((name) => name.endsWith("-timing.json"));
+}
+
+describe("consumeNpmInstallTimingAttributes", () => {
+  it("converts the whitelisted timers from milliseconds to seconds", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      metadata: { version: "11.16.0" },
+      timers: {
+        idealTree: 230,
+        reify: 24500,
+        "reify:build": 90,
+        "reify:loadTrees": 400,
+        "reify:unpack": 23200,
+      },
+      unfinishedTimers: {},
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toEqual({
+      "superblocks.npm.install.build_seconds": 0.09,
+      "superblocks.npm.install.ideal_tree_seconds": 0.23,
+      "superblocks.npm.install.load_trees_seconds": 0.4,
+      "superblocks.npm.install.reify_seconds": 24.5,
+      "superblocks.npm.install.unpack_seconds": 23.2,
+    });
+  });
+
+  // npm records one `reifyNode:node_modules/<package>` timer per package it
+  // touched. Emitting those would be unbounded attribute cardinality and would
+  // put dependency names into telemetry, so only the fixed whitelist is ever
+  // emitted.
+  it("never emits a per-package reifyNode timer", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: {
+        idealTree: 100,
+        "reifyNode:node_modules/@dnd-kit/core": 12,
+        "reifyNode:node_modules/lodash": 34,
+        "reifyNode:node_modules/react": 56,
+      },
+    });
+
+    const attributes = await consumeNpmInstallTimingAttributes(logsDir);
+
+    expect(attributes).toEqual({
+      "superblocks.npm.install.ideal_tree_seconds": 0.1,
+    });
+    expect(
+      Object.keys(attributes ?? {}).some((key) => key.includes("reifyNode")),
+    ).toBe(false);
+  });
+
+  // Which phases npm records depends on what the install did, so a missing
+  // timer is normal rather than an error.
+  it("omits timers npm did not record", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { reify: 500 },
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toEqual({
+      "superblocks.npm.install.reify_seconds": 0.5,
+    });
+  });
+
+  // "npm unpacked nothing" is the signal that separates a metadata-only
+  // install from one that wrote tens of thousands of files, so a recorded zero
+  // is real data and must not be dropped as if it were missing.
+  it("emits a recorded zero rather than dropping it", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { "reify:unpack": 0 },
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toEqual({
+      "superblocks.npm.install.unpack_seconds": 0,
+    });
+  });
+
+  // npm's log ids are fixed-width ISO timestamps, so the newest file is the
+  // last one alphabetically.
+  it("reads the newest file when older installs left files behind", async () => {
+    await writeTimingFile("2026-08-07T11_00_00_000Z", {
+      timers: { reify: 1000 },
+    });
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { reify: 2000 },
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toEqual({
+      "superblocks.npm.install.reify_seconds": 2,
+    });
+  });
+
+  // npm's `logs-max` pruning only covers its debug logs, so timing files would
+  // pile up on the app volume forever if nothing removed them.
+  it("removes the timing files it read so they cannot accumulate", async () => {
+    await writeTimingFile("2026-08-07T11_00_00_000Z", {
+      timers: { reify: 1000 },
+    });
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { reify: 2000 },
+    });
+    const debugLog = path.join(logsDir, "2026-08-07T12_00_00_000Z-debug-0.log");
+    await nodeFs.writeFile(debugLog, "npm debug output");
+
+    await consumeNpmInstallTimingAttributes(logsDir);
+
+    expect(await listTimingFiles()).toEqual([]);
+    // npm's debug log is a separate diagnostic that must survive.
+    await expect(nodeFs.readFile(debugLog, "utf8")).resolves.toBe(
+      "npm debug output",
+    );
+  });
+
+  it("returns null when the logs dir has no timing file", async () => {
+    await nodeFs.writeFile(
+      path.join(logsDir, "2026-08-07T12_00_00_000Z-debug-0.log"),
+      "npm debug output",
+    );
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toBeNull();
+  });
+
+  it("returns null when the logs dir does not exist", async () => {
+    expect(
+      await consumeNpmInstallTimingAttributes(path.join(logsDir, "missing")),
+    ).toBeNull();
+  });
+
+  it("returns null for a file that is not JSON rather than throwing", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", "not json at all");
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toBeNull();
+  });
+
+  it("returns null when the file carries no timers object", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", { metadata: {} });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toBeNull();
+  });
+
+  it("returns null when none of the whitelisted timers are present", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { "npm:load": 12, "reifyNode:node_modules/lodash": 34 },
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toBeNull();
+  });
+
+  it("ignores timer values that are not finite numbers", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { idealTree: "230", reify: null, "reify:unpack": 23200 },
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toEqual({
+      "superblocks.npm.install.unpack_seconds": 23.2,
+    });
+  });
+
+  it("clamps a negative duration so dashboards cannot be skewed", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { reify: -500 },
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toEqual({
+      "superblocks.npm.install.reify_seconds": 0,
+    });
+  });
+});

package/src/telemetry/logging.test.ts

@@ -156,6 +156,61 @@ describe("telemetry logger error sanitization", () => {
   });
 });
 
+describe("telemetry logger infoStructured", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("emits an INFO record carrying structured attributes (not flattened into the body)", () => {
+    const logger = getLogger();
+
+    logger.infoStructured?.("Package installation completed successfully", {
+      "superblocks.npm.install.added": 8,
+      "superblocks.npm.install.duration_seconds": 32.5,
+      "superblocks.npm.install.outcome": "success",
+    });
+
+    expect(emitMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        severityText: "INFO",
+        body: "sanitized-message:Package installation completed successfully",
+        attributes: {
+          "superblocks.npm.install.added": 8,
+          "superblocks.npm.install.duration_seconds": 32.5,
+          "superblocks.npm.install.outcome": "sanitized-object:success",
+        },
+      }),
+    );
+    // Winston gets the body only (structured attributes go to OTel, not also
+    // to stdout log shippers as a duplicate).
+    expect(winstonLoggerMock.info).toHaveBeenCalledWith(
+      "sanitized-message:Package installation completed successfully",
+    );
+  });
+
+  it("strips secret-named attribute keys before emitting", () => {
+    const logger = getLogger();
+
+    logger.infoStructured?.("install done", {
+      registry: "https://npm.example.com",
+      token: "[REDACTED:token]",
+    });
+
+    expect(emitMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        attributes: expect.objectContaining({
+          registry: "sanitized-object:https://npm.example.com",
+        }),
+      }),
+    );
+    expect(emitMock).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        attributes: expect.objectContaining({ token: expect.anything() }),
+      }),
+    );
+  });
+});
+
 describe("telemetry logger warnStructured", () => {
   beforeEach(() => {
     vi.clearAllMocks();

package/src/telemetry/logging.ts

@@ -79,6 +79,13 @@ export interface Logger {
   debug: (...messages: unknown[]) => void;
   info: (...messages: unknown[]) => void;
   warn: (...messages: unknown[]) => void;
+  /**
+   * Emit an INFO-level log whose structured attributes are exported as OTel
+   * log attributes (Datadog facets) instead of being flattened into the
+   * message body. Plain `info()` joins every argument into one body string, so
+   * attributes passed to it are never queryable.
+   */
+  infoStructured?: (message: string, attributes: LogAttributes) => void;
   /**
    * Emit a WARN-level log whose structured attributes are exported as OTel log
    * attributes (Datadog facets) instead of being flattened into the message
@@ -120,6 +127,18 @@ const logger: Logger = Object.freeze({
     });
     winstonLogger.warn(body);
   },
+  infoStructured: (message: string, attributes: LogAttributes) => {
+    const body = sanitizeLogMessage(message);
+    // Same sanitize-then-emit contract as warnStructured below.
+    const safeAttributes = sanitizeLogObject(attributes);
+    getTracedLogger().emit({
+      severityNumber: SeverityNumber.INFO,
+      severityText: "INFO",
+      body,
+      attributes: safeAttributes,
+    });
+    winstonLogger.info(body);
+  },
   warnStructured: (message: string, attributes: LogAttributes) => {
     const body = sanitizeLogMessage(message);
     // sanitizeLogObject strips secret-named keys and redacts secret values,
@@ -174,6 +193,8 @@ export function getLogger(
     // above, it forwards raw args to the supplied function and does NOT
     // sanitize or emit OTel attributes. Production callers use the default
     // logger (and the vite-plugin wrapLogger) which sanitize before emitting.
+    infoStructured: (message: string, attributes: LogAttributes) =>
+      loggerOverride(message, attributes),
     warnStructured: (message: string, attributes: LogAttributes) =>
       loggerOverride(message, attributes),
     error: loggerOverride as (message: string, meta?: ErrorMeta) => void,