@elisra-devops/docgen-data-provider 1.140.0 → 1.142.0

package/bin/utils/logger.js

@@ -1,35 +1,274 @@
 'use strict';
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagnosticsTransport = exports.redact = exports.withRunContext = void 0;
+exports.redactValue = redactValue;
 const winston = require("winston");
+const fs = require("fs");
+const path = require("path");
+const Transport = require("winston-transport");
+const runContext_1 = require("./runContext");
+const logSink_1 = require("./logSink");
 let logger;
-const logFormat = winston.format.printf((info) => `${info.timestamp} - ${info.level}: ${info.message}`);
-// if (typeof window === "undefined") {
-//   let logsPath = process.env.logs_path || "./logs/";
-//   logger = winston.createLogger({
-//     format: winston.format.timestamp(),
-//     level: "silly",
-//     transports: [
-//       new winston.transports.File({
-//         filename: `${logsPath}azure-rest-api-errors.log`,
-//         level: "error",
-//         format: logFormat,
-//       }),
-//       new winston.transports.File({
-//         filename: `${logsPath}azure-rest-api-all.log`,
-//         format: logFormat,
-//       }),
-//       new winston.transports.Console({ format: logFormat, level: "debug" }),
-//     ],
-//   });
-// } else {
+// Merges the ambient runId (set by content-control's request middleware, once Phase 3 lands
+// there) into every log record. A never-populated store is a harmless no-op — this package
+// only reads it, never sets it.
+exports.withRunContext = winston.format((info) => {
+    const store = runContext_1.runContextStore.getStore();
+    if (store === null || store === void 0 ? void 0 : store.runId)
+        info.runId = store.runId;
+    // Phase 7b — same ambient, per-run treatment as runId.
+    if (store === null || store === void 0 ? void 0 : store.docType)
+        info.docType = store.docType;
+    // Phase 7c — same read-only treatment; populated by content-control's attachRunContext.
+    if (store === null || store === void 0 ? void 0 : store.project)
+        info.project = store.project;
+    return info;
+});
+// Defense-in-depth: scrubs known-sensitive keys out of any object attached to a log call
+// (meta, splat, an Error's own enumerable props — e.g. AxiosError.toJSON()'s
+// config.auth.password / config.headers.Authorization, which is exactly how a PAT was
+// leaking via `logger.error(JSON.stringify(error))` on ADO REST failures). Does not
+// redact secrets interpolated into a message string — that's the corresponding call-site
+// fixes' job; this is a backstop for structured fields.
+// "accesskey" (not just "minioaccesskey") so this also catches an *AccessKeyId-style field —
+// a real gap found in api-gate's copy during the Phase 5 manifest work: only the *SecretKey
+// sibling was covered before, via "secret". Applied here too to keep the four copies in sync.
+const SENSITIVE_KEY = /token|pat|password|secret|authorization|accesskey|minioaccesskey|miniosecretkey/i;
+// A per-key try/catch on the *read*, not just around the whole loop: a getter that throws
+// (e.g. `{ get boom() { throw ... } }`) would otherwise abort redaction for every remaining
+// key in the same object, or — worse — survive redaction untouched and re-throw later, inside
+// winston's json() formatter, which is not wrapped in anything. redactValue always returns a
+// freshly built plain object/array, never the original reference, so once a value has passed
+// through here nothing downstream can re-trigger a throwing accessor on it.
+function safeRead(obj, key) {
+    try {
+        return { ok: true, value: obj[key] };
+    }
+    catch (_a) {
+        return { ok: false };
+    }
+}
+function redactValue(value, depth = 0, seen = new WeakSet()) {
+    if (depth > 6 || value === null || typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return '[Circular]';
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map((v) => redactValue(v, depth + 1, seen));
+    const out = {};
+    for (const key of Object.keys(value)) {
+        const read = safeRead(value, key);
+        if (!read.ok) {
+            out[key] = '[Unreadable property]';
+            continue;
+        }
+        out[key] = SENSITIVE_KEY.test(key) ? '[REDACTED]' : redactValue(read.value, depth + 1, seen);
+    }
+    return out;
+}
+exports.redact = winston.format((info) => {
+    const target = info;
+    for (const key of Object.keys(target)) {
+        // level/timestamp are always plain strings winston sets itself — never touched. message is
+        // NOT exempt: when logger.error(x) is called with a single non-string/non-Error argument,
+        // winston nests the whole thing under info.message (this is exactly the shape hit by a raw
+        // object argument), so message can carry a throwing getter or a sensitive key just as much
+        // as any other field — redactValue already no-ops on a plain string, so including it here
+        // costs nothing for the common case and closes that gap for the uncommon one.
+        if (key === 'level' || key === 'timestamp')
+            continue;
+        const read = safeRead(target, key);
+        const value = !read.ok
+            ? '[Unreadable property]'
+            : // A top-level primitive (e.g. token: "abc") has no children for redactValue to walk into —
+                // the key itself has to be checked here too, not just inside the recursive object walk.
+                SENSITIVE_KEY.test(key)
+                    ? '[REDACTED]'
+                    : redactValue(read.value);
+        try {
+            target[key] = value;
+        }
+        catch (_a) {
+            // The original property could be a getter-only accessor with no setter, which throws on
+            // plain assignment in strict mode — redefine it outright rather than skip it.
+            Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+        }
+    }
+    return info;
+});
+// Resolves the package's own version for defaultMeta. Node-only (this package is currently
+// only ever consumed by docgen-content-control at runtime — the browser transport below is
+// unused/commented out), so fs/path are safe here.
+function readOwnVersion() {
+    const candidates = [
+        path.resolve(__dirname, '../package.json'),
+        path.resolve(__dirname, '../../package.json'),
+        path.resolve(process.cwd(), 'package.json'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            if (!fs.existsSync(candidate))
+                continue;
+            return JSON.parse(fs.readFileSync(candidate, 'utf8')).version || 'unknown';
+        }
+        catch (_a) {
+            // try next candidate
+        }
+    }
+    return 'unknown';
+}
+// A template literal's implicit ToString throws on a Symbol value (unlike String(), which
+// calls Symbol.prototype.toString() explicitly) — logger.error(Symbol('x')) would otherwise
+// crash inside this formatter itself, the one place in the pipeline with no try/catch around
+// it. Symbol.toString() itself never throws, so this needs no further guarding.
+const safeMessageString = (value) => typeof value === 'symbol' ? value.toString() : String(value);
+// A failed ADO request's description (helpers/requestContext.ts), attached to the thrown error
+// and merged onto the record by winston. In text mode — the default, which prints only the
+// message — this is the only way the URL reaches stdout for a record whose own message doesn't
+// carry it. Never throws: this runs inside the formatter, which has no try/catch around it.
+const requestSuffix = (ctx) => {
+    try {
+        if (!ctx || typeof ctx !== 'object')
+            return '';
+        const c = ctx;
+        if (typeof c.url !== 'string')
+            return '';
+        const method = typeof c.method === 'string' ? `${c.method} ` : '';
+        const status = typeof c.status === 'number' ? ` -> ${c.status}` : '';
+        return ` [${method}${c.url}${status}]`;
+    }
+    catch (_a) {
+        return '';
+    }
+};
+const textFormat = winston.format.printf((info) => `${info.timestamp} - ${info.level}: ${safeMessageString(info.message)}${requestSuffix(info.adoRequest)}`);
+// Bounded so one oversized message/stack can't produce an unbounded LogEvent document.
+const MAX_MESSAGE_LEN = 2000;
+const MAX_STACK_LEN = 4000;
+function clamp(value, max) {
+    if (typeof value !== 'string')
+        return undefined;
+    return value.length > max ? value.slice(0, max) : value;
+}
+// Re-validates the request description at the transport instead of trusting its shape — it
+// arrives via an Error's own properties, which anything upstream could have set. Allowlisted
+// keys only, each type-checked and bounded.
+function pickContext(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const c = raw;
+    const context = {};
+    const method = clamp(c.method, logSink_1.CONTEXT_LIMITS.method);
+    const url = clamp(c.url, logSink_1.CONTEXT_LIMITS.url);
+    const requestBody = clamp(c.requestBody, logSink_1.CONTEXT_LIMITS.requestBody);
+    const responseExcerpt = clamp(c.responseExcerpt, logSink_1.CONTEXT_LIMITS.responseExcerpt);
+    if (method)
+        context.method = method;
+    if (url)
+        context.url = url;
+    if (requestBody)
+        context.requestBody = requestBody;
+    if (responseExcerpt)
+        context.responseExcerpt = responseExcerpt;
+    if (typeof c.status === 'number' && Number.isFinite(c.status))
+        context.status = c.status;
+    if (typeof c.attempt === 'number' && Number.isFinite(c.attempt))
+        context.attempt = c.attempt;
+    return Object.keys(context).length ? context : undefined;
+}
+// Ships warn/error records to whatever LogSink the host process (docgen-content-control's
+// index.ts) has installed — this package never installs one itself, only reads it. This is
+// the dominant source of real ADO error records (tfs.ts's executeWithRetry is the single
+// static axios instance handling all Azure DevOps traffic), so without this transport most
+// real generation failures either never reach the store or get misattributed to
+// dg-content-control. Reads info *after* the rest of the format chain has already run —
+// redact() has already scrubbed it by the time this transport sees it. Never throws, never
+// blocks the call path, and never logs through `logger` itself (that would recurse back
+// into this same transport) — failures go to console.error only.
+const DIAGNOSTICS_CAPTURE_ENABLED = (process.env.DIAGNOSTICS_CAPTURE_ENABLED || 'true').toLowerCase() !== 'false';
+// Exported for tests, the same treatment as redact()/withRunContext() — so a test pipeline
+// can exercise this transport without going through the real singleton logger's env-gated
+// json()/textFormat branch.
+class DiagnosticsTransport extends Transport {
+    log(info, callback) {
+        var _a, _b, _c, _d, _e;
+        setImmediate(() => this.emit('logged', info));
+        try {
+            const level = info.level;
+            const isWarnOrError = level === 'warn' || level === 'error';
+            // Phase 6b — the logger's own level gate is now 'debug' (see createLogger below), so a
+            // debug/info call reaches this transport regardless of mode; this is the one place that
+            // decides whether it's actually persisted, keyed off the per-run capture mode rather
+            // than a process-wide setting — concurrent runs in 'normal' mode are unaffected by a
+            // sibling run's 'verbose'/'retain-on-failure' opt-in.
+            const captureMode = (_a = runContext_1.runContextStore.getStore()) === null || _a === void 0 ? void 0 : _a.captureMode;
+            const isCapturedDebugOrInfo = (level === 'debug' || level === 'info') && (captureMode === 'verbose' || captureMode === 'retain-on-failure');
+            if (DIAGNOSTICS_CAPTURE_ENABLED && (isWarnOrError || isCapturedDebugOrInfo)) {
+                // winston.errors({stack:true}) merges an Error's own enumerable properties (stack,
+                // and anything else the call site set, e.g. `err.code`) directly onto `info` — there
+                // is no separate nested info.err. `info.stack`'s presence is the only reliable signal
+                // that this record came from `logger.error('...', err)`/`logger.error(err)` rather
+                // than a plain string message. When present, info.message is already the
+                // stable-message-plus-error-message string winston produced, so err.message reuses it.
+                const hasErr = typeof info.stack === 'string';
+                const message = (_b = clamp(info.message, MAX_MESSAGE_LEN)) !== null && _b !== void 0 ? _b : '';
+                const event = {
+                    ts: typeof info.timestamp === 'string' ? info.timestamp : new Date().toISOString(),
+                    level: String(info.level),
+                    service: String((_c = info.service) !== null && _c !== void 0 ? _c : '@elisra-devops/docgen-data-provider'),
+                    version: String((_d = info.version) !== null && _d !== void 0 ? _d : 'unknown'),
+                    runId: typeof info.runId === 'string' ? info.runId : undefined,
+                    docType: typeof info.docType === 'string' ? info.docType : undefined,
+                    step: typeof info.step === 'string' ? info.step : undefined,
+                    contentControlType: typeof info.contentControlType === 'string' ? info.contentControlType : undefined,
+                    contentControlTitle: typeof info.contentControlTitle === 'string' ? info.contentControlTitle : undefined,
+                    project: typeof info.project === 'string' ? info.project : undefined,
+                    userId: typeof info.userId === 'string' ? info.userId : undefined,
+                    message,
+                    err: hasErr
+                        ? {
+                            message,
+                            code: typeof info.code === 'string' ? info.code : undefined,
+                            stack: clamp(info.stack, MAX_STACK_LEN),
+                        }
+                        : undefined,
+                    context: pickContext(info.adoRequest),
+                    retainPending: !isWarnOrError && captureMode === 'retain-on-failure' ? true : undefined,
+                };
+                (_e = (0, logSink_1.getLogSink)()) === null || _e === void 0 ? void 0 : _e.push(event);
+            }
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error('DiagnosticsTransport failed to push event', e);
+        }
+        callback();
+    }
+}
+exports.DiagnosticsTransport = DiagnosticsTransport;
+// LOG_FORMAT=json is the eventual default (structured stdout a collector can parse), but
+// stays opt-in for one release so switching is a config change, not an image rebuild, if
+// anyone reading raw console output needs to roll back.
+const useJson = (process.env.LOG_FORMAT || 'text').toLowerCase() === 'json';
+// Phase 6b — the Logger's own level gate must be 'debug' (winston's most permissive) so a
+// debug/info call always reaches every transport's log(); a static per-logger level can't
+// depend on the ALS store's per-run capture mode, so DiagnosticsTransport has to be the one
+// deciding what's actually persisted. The Console transport below gets its own explicit
+// level so stdout's default behavior (info/warn/error unless LOG_LEVEL=debug) is unchanged —
+// this only spends the format-chain cost on debug() calls that previously short-circuited
+// for free; info/warn/error volume (Phase 4's focus) is unaffected either way.
+const CONSOLE_LOG_LEVEL = process.env.LOG_LEVEL || 'info';
 logger = winston.createLogger({
-    format: winston.format.timestamp(),
-    level: 'silly',
-    transports: [
-        new winston.transports.Console({ format: logFormat, level: 'debug' }),
-        // new BrowserConsole({ format: logFormat, level: 'debug' }),
-    ],
+    level: 'debug',
+    defaultMeta: { service: '@elisra-devops/docgen-data-provider', version: readOwnVersion() },
+    format: useJson
+        ? winston.format.combine(winston.format.errors({ stack: true }), winston.format.timestamp(), (0, exports.withRunContext)(), (0, exports.redact)(), winston.format.splat(), winston.format.json())
+        : winston.format.combine(winston.format.errors({ stack: true }), winston.format.timestamp(), (0, exports.withRunContext)(), (0, exports.redact)(), winston.format.splat(), textFormat),
+    // Stdout only — no File transports, consistent with the other DocGen services (no mounted
+    // log volume anywhere in this deployment, so a File transport is invisible to `kubectl logs`
+    // and can throw at import time under a read-only root filesystem).
+    transports: [new winston.transports.Console({ level: CONSOLE_LOG_LEVEL }), new DiagnosticsTransport()],
 });
-// }
 exports.default = logger;
 //# sourceMappingURL=logger.js.map

package/bin/utils/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AACb,mCAAmC;AAEnC,IAAI,MAAsB,CAAC;AAE3B,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,MAAM,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;AACxG,uCAAuC;AACvC,uDAAuD;AAEvD,oCAAoC;AACpC,0CAA0C;AAC1C,sBAAsB;AACtB,oBAAoB;AACpB,sCAAsC;AACtC,4DAA4D;AAC5D,0BAA0B;AAC1B,6BAA6B;AAC7B,YAAY;AACZ,sCAAsC;AACtC,yDAAyD;AACzD,6BAA6B;AAC7B,YAAY;AACZ,+EAA+E;AAC/E,SAAS;AACT,QAAQ;AACR,WAAW;AACX,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAC5B,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE;IAClC,KAAK,EAAE,OAAO;IACd,UAAU,EAAE;QACV,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QACrE,6DAA6D;KAC9D;CACF,CAAC,CAAC;AACH,IAAI;AAEJ,kBAAe,MAAM,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}

package/bin/utils/runContext.d.ts

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from 'async_hooks';
+export interface RunContext {
+    runId: string;
+    captureMode?: 'verbose' | 'retain-on-failure';
+    docType?: string;
+    project?: string;
+}
+export declare const runContextStore: AsyncLocalStorage<RunContext>;

package/bin/utils/runContext.js

@@ -0,0 +1,12 @@
+'use strict';
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runContextStore = void 0;
+const async_hooks_1 = require("async_hooks");
+// Symbol.for uses the global symbol registry, so every duplicated copy of this file across
+// the DocGen packages — hoisted or nested at any depth by npm — converges on the same
+// AsyncLocalStorage instance. Keying by module identity instead would silently split into
+// two stores and runId would go missing with no visible error.
+const KEY = Symbol.for('elisradevops.docgen.runContext');
+exports.runContextStore = (_a = globalThis[KEY]) !== null && _a !== void 0 ? _a : (globalThis[KEY] = new async_hooks_1.AsyncLocalStorage());
+//# sourceMappingURL=runContext.js.map

package/bin/utils/runContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runContext.js","sourceRoot":"","sources":["../../src/utils/runContext.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;;;;AACb,6CAAgD;AAehD,2FAA2F;AAC3F,sFAAsF;AACtF,0FAA0F;AAC1F,+DAA+D;AAC/D,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;AAE5C,QAAA,eAAe,GAC1B,MAAE,UAAsC,CAAC,GAAG,CAA+C,mCAC3F,CAAE,UAAsC,CAAC,GAAG,CAAC,GAAG,IAAI,+BAAiB,EAAc,CAAC,CAAC"}

package/eslint.config.mjs

@@ -0,0 +1,40 @@
+import tseslint from 'typescript-eslint';
+import globals from 'globals';
+
+// Phase 4 regression guard: bans the two log-record-corrupting patterns the observability plan
+// found and fixed by hand across all four backend repos. Deliberately does NOT extend
+// js.configs.recommended/tseslint's recommended rule sets — this repo has never had a linter,
+// and pulling in a general rule set now would surface a large, unrelated pre-existing backlog
+// (unused vars, etc.) as new lint failures. Scope is exactly the one regression this guards
+// against. Keep this file identical in shape across docgen-api-gate / docgen-content-control /
+// docgen-data-provider-package / docgen-dg-skins-package — see each repo's CLAUDE.md "keep
+// these files in sync" note.
+export default tseslint.config(
+  {
+    ignores: ['bin/**', 'coverage/**', '**/test/**', '**/tests/**'],
+  },
+  {
+    files: ['src/**/*.ts'],
+    extends: [tseslint.configs.base],
+    languageOptions: {
+      globals: globals.node,
+    },
+    rules: {
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector:
+            "CallExpression[callee.object.name='logger'] > :matches(TemplateLiteral, BinaryExpression[operator='+']).arguments:first-child MemberExpression[property.name='stack']",
+          message:
+            'Do not embed .stack in the log message string — errors({stack:true}) attaches it automatically when the Error is passed as an argument. Pass the Error itself as a positional/meta argument instead.',
+        },
+        {
+          selector:
+            "CallExpression[callee.object.name='logger'] CallExpression[callee.object.name='JSON'][callee.property.name='stringify'] > Identifier.arguments:first-child[name=/^(e|err|error|ex)$/]",
+          message:
+            "Don't JSON.stringify an Error — message/stack are non-enumerable and it serializes to {}. Pass the Error object directly as a log argument.",
+        },
+      ],
+    },
+  }
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elisra-devops/docgen-data-provider",
-  "version": "1.140.0",
+  "version": "1.142.0",
   "description": "A document generator data provider, aimed to retrive data from azure devops",
   "repository": {
     "type": "git",
@@ -11,9 +11,11 @@
   "types": "./bin/index.d.ts",
   "scripts": {
     "test": "jest --coverage --runInBand --forceExit",
-    "build": "tsc"
+    "build": "tsc",
+    "lint": "eslint ."
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
     "@types/babel__generator": "^7.6.8",
     "@types/babel__template": "^7.4.4",
     "@types/caseless": "^0.12.5",
@@ -24,11 +26,14 @@
     "@types/yargs-parser": "^21.0.3",
     "baseline-browser-mapping": "^2.9.0",
     "dotenv": "^16.4.5",
+    "eslint": "^9.39.5",
+    "globals": "^15.15.0",
     "jest": "^29.7.0",
     "jest-junit": "^16.0.0",
     "npm": "^10.8.2",
     "ts-jest": "^29.2.3",
-    "typescript": "^5.5.4"
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^8.71.0"
   },
   "dependencies": {
     "@types/xml2js": "^0.4.5",