@elisra-devops/docgen-data-provider 1.141.0 → 1.143.0

package/src/tests/helpers/requestContext.test.ts

@@ -0,0 +1,252 @@
+import logger from '../../utils/logger';
+import {
+  sanitizeUrl,
+  summarizeBody,
+  summarizeResponse,
+  buildAdoRequestContext,
+  annotateAdoError,
+  maskWiqlLiterals,
+  templatePath,
+  describeError,
+  logCaughtError,
+} from '../../helpers/requestContext';
+
+describe('maskWiqlLiterals', () => {
+  it('replaces every quoted literal with its length', () => {
+    expect(maskWiqlLiterals("a = 'xy' and b = ''")).toBe("a = '[2 chars]' and b = '[0 chars]'");
+  });
+});
+
+describe('sanitizeUrl', () => {
+  it('returns undefined for a missing or empty url', () => {
+    expect(sanitizeUrl(undefined)).toBeUndefined();
+    expect(sanitizeUrl('')).toBeUndefined();
+  });
+
+  it('keeps a normal ADO url intact', () => {
+    const url = 'https://dev.azure.com/org/proj/_apis/wit/queries/abc?$depth=1&api-version=7.0';
+    expect(sanitizeUrl(url)).toBe(url);
+  });
+
+  it('strips credentials embedded in the url', () => {
+    const out = sanitizeUrl('https://user:s3cret@dev.azure.com/org/_apis/projects');
+    expect(out).not.toContain('s3cret');
+    expect(out).not.toContain('user');
+    expect(out).toContain('dev.azure.com/org/_apis/projects');
+  });
+
+  it('masks sensitive query parameter values but keeps ordinary ones', () => {
+    const out = sanitizeUrl('https://host/api?access_token=abc123&top=10&sig=zzz&keywords=release')!;
+    expect(out).not.toContain('abc123');
+    expect(out).not.toContain('zzz');
+    expect(out).toContain('top=10');
+    expect(out).toContain('keywords=release');
+  });
+
+  it('leaves non-sensitive parameters byte-identical when masking another', () => {
+    expect(sanitizeUrl('https://h/api?$filter=a%20b&token=x&q=a+b')).toBe('https://h/api?$filter=a%20b&token=[REDACTED]&q=a+b');
+  });
+
+  it('passes a non-absolute url through, bounded', () => {
+    expect(sanitizeUrl('/relative/path')).toBe('/relative/path');
+    expect(sanitizeUrl('x'.repeat(5000))!.length).toBeLessThanOrEqual(1001);
+  });
+});
+
+describe('summarizeBody', () => {
+  it('never describes a GET body', () => {
+    expect(summarizeBody({ query: 'SELECT 1' }, 'get')).toBeUndefined();
+    expect(summarizeBody({ query: 'SELECT 1' }, 'HEAD')).toBeUndefined();
+  });
+
+  it('returns undefined for an empty body — the default `{}` callers pass', () => {
+    expect(summarizeBody({}, 'post')).toBeUndefined();
+    expect(summarizeBody([], 'post')).toBeUndefined();
+    expect(summarizeBody(null, 'post')).toBeUndefined();
+    expect(summarizeBody('', 'post')).toBeUndefined();
+  });
+
+  it('keeps a WIQL-style body so the failing query is visible', () => {
+    const out = summarizeBody({ query: "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = 'P'" }, 'post')!;
+    expect(out).toContain('SELECT [System.Id] FROM WorkItems');
+    expect(out).toContain("[System.TeamProject] = '[1 chars]'");
+    expect(out).not.toContain("= 'P'");
+  });
+
+  it('masks WIQL literals (incl. escaped quotes) but keeps fields, numbers and macros', () => {
+    const out = summarizeBody({ query: "SELECT [Id] FROM WorkItems WHERE [Title] = 'it''s secret' AND [Assigned] = @Me AND [Id] > 42" }, 'post')!;
+    expect(out).not.toContain('secret');
+    expect(out).toContain("[Title] = '[12 chars]'");
+    expect(out).toContain('@Me');
+    expect(out).toContain('> 42');
+  });
+
+  it('keeps an id-list body', () => {
+    expect(summarizeBody({ ids: [1, 2, 3], fields: ['System.Title'] }, 'post')).toBe(
+      '{"ids":[1,2,3],"fields":["System.Title"]}'
+    );
+  });
+
+  it('redacts credential-looking keys at any depth', () => {
+    const out = summarizeBody({ query: 'q', auth: { token: 'tok-123', password: 'pw-456' }, pat: 'pat-789' }, 'post')!;
+    expect(out).not.toContain('tok-123');
+    expect(out).not.toContain('pw-456');
+    expect(out).not.toContain('pat-789');
+    expect(out).toContain('[REDACTED]');
+    expect(out).toContain('"query":"q"');
+  });
+
+  it('JSON-Patch bodies keep op + path only — field values are dropped', () => {
+    const patch = [
+      { op: 'add', path: '/fields/System.Title', value: 'Highly classified title' },
+      { op: 'replace', path: '/fields/System.Description', value: { html: '<p>secret</p>' } },
+    ];
+    const out = summarizeBody(patch, 'patch')!;
+    expect(out).toContain('json-patch (2 ops, values omitted)');
+    expect(out).toContain('add /fields/System.Title');
+    expect(out).toContain('replace /fields/System.Description');
+    expect(out).not.toContain('classified');
+    expect(out).not.toContain('secret');
+  });
+
+  it('bounds a long string value and the whole body', () => {
+    const one = summarizeBody({ query: 'x'.repeat(5000) }, 'post')!;
+    expect(one.length).toBeLessThan(700);
+    const many = summarizeBody(Object.fromEntries(Array.from({ length: 300 }, (_, i) => [`k${i}`, 'v'.repeat(40)])), 'post')!;
+    expect(many.length).toBeLessThanOrEqual(2001);
+  });
+
+  it('caps a very long array', () => {
+    const out = summarizeBody({ ids: Array.from({ length: 500 }, (_, i) => i) }, 'post')!;
+    expect(out).toContain('more');
+  });
+
+  it('describes non-JSON bodies by type and size only', () => {
+    expect(summarizeBody(Buffer.from('abcdef'), 'post')).toBe('[binary, 6 bytes]');
+    expect(summarizeBody('not json at all', 'post')).toBe('[text, 15 chars]');
+    expect(summarizeBody(42, 'post')).toBe('[number]');
+    expect(summarizeBody({ pipe: () => undefined }, 'post')).toBe('[stream]');
+  });
+
+  it('parses a JSON string body and summarizes it like an object', () => {
+    expect(summarizeBody('{"query":"q"}', 'post')).toBe('{"query":"q"}');
+  });
+
+  it('never throws on a body it cannot serialize', () => {
+    expect(summarizeBody({ n: BigInt(1) }, 'post')).toBe('[unserializable body]');
+    const circular: Record<string, unknown> = { a: 1 };
+    circular.self = circular;
+    expect(() => summarizeBody(circular, 'post')).not.toThrow();
+  });
+});
+
+describe('summarizeResponse', () => {
+  it('prefers the server message (ADO puts its explanation there)', () => {
+    expect(summarizeResponse({ message: 'TF401232: Work item 5 does not exist', typeName: 'x' })).toBe(
+      'TF401232: Work item 5 does not exist'
+    );
+  });
+
+  it('truncates a text response (e.g. an HTML error page) to 200 chars', () => {
+    expect(summarizeResponse('<html>'.repeat(200))!.length).toBeLessThanOrEqual(201);
+  });
+
+  it('falls back to a redacted, bounded JSON dump when there is no message', () => {
+    const out = summarizeResponse({ code: 1, token: 'leak-me' })!;
+    expect(out).not.toContain('leak-me');
+    expect(out).toContain('"code":1');
+  });
+
+  it('does not walk a stream response', () => {
+    expect(summarizeResponse({ pipe: () => undefined, socket: { a: 1 } })).toBe('[stream]');
+  });
+
+  it('ignores a missing or binary response', () => {
+    expect(summarizeResponse(undefined)).toBeUndefined();
+    expect(summarizeResponse(Buffer.from('x'))).toBeUndefined();
+  });
+});
+
+describe('buildAdoRequestContext', () => {
+  it('describes a failed GET with method, status, attempt and the server message', () => {
+    const err = { response: { status: 404, data: { message: 'not found' } } };
+    expect(buildAdoRequestContext(err, { method: 'get', url: 'https://h/_apis/x' }, 2)).toEqual({
+      method: 'GET',
+      url: 'https://h/_apis/x',
+      status: 404,
+      attempt: 2,
+      responseExcerpt: 'not found',
+    });
+  });
+
+  it('includes a summarized body for a POST and omits fields it does not have', () => {
+    const ctx = buildAdoRequestContext(new Error('boom'), { method: 'post', url: 'https://h/wiql', data: { query: 'q' } });
+    expect(ctx).toEqual({ method: 'POST', url: 'https://h/wiql', requestBody: '{"query":"q"}' });
+  });
+
+  it('falls back to the axios error config when the request is not described explicitly', () => {
+    const ctx = buildAdoRequestContext({ config: { method: 'put', url: 'https://h/y' } }, {});
+    expect(ctx.method).toBe('PUT');
+    expect(ctx.url).toBe('https://h/y');
+  });
+});
+
+describe('annotateAdoError', () => {
+  it('attaches the context as an enumerable property winston will merge onto the record', () => {
+    const err = annotateAdoError(new Error('x'), { method: 'GET', url: 'https://h/z' });
+    expect(Object.keys(err)).toContain('adoRequest');
+    expect((err as any).adoRequest.url).toBe('https://h/z');
+  });
+
+  it('never throws on a frozen or non-object error', () => {
+    expect(() => annotateAdoError(Object.freeze(new Error('x')), { url: 'u' })).not.toThrow();
+    expect(() => annotateAdoError('a string' as any, { url: 'u' })).not.toThrow();
+    expect(() => annotateAdoError(undefined as any, { url: 'u' })).not.toThrow();
+  });
+});
+
+describe('templatePath', () => {
+  it('drops origin and query and collapses numeric / guid segments', () => {
+    expect(templatePath('https://dev.azure.com/org/p/_apis/wit/workitems/123?api-version=7')).toBe(
+      '/org/p/_apis/wit/workitems/{id}'
+    );
+    expect(templatePath('https://h/a/3f2504e0-4f89-11d3-9a0c-0305e82c3301/b')).toBe('/a/{id}/b');
+  });
+  it('copes with a relative or missing url', () => {
+    expect(templatePath('/rel/42?x=1')).toBe('/rel/{id}');
+    expect(templatePath(undefined)).toBe('(unknown url)');
+  });
+});
+
+describe('describeError', () => {
+  it('carries the original message separately so the dashboard err.message is not the combined line', () => {
+    expect(describeError(new Error('boom'))).toMatchObject({ message: 'boom', errMessage: 'boom' });
+  });
+});
+
+describe('logCaughtError', () => {
+  beforeEach(() => {
+    jest.spyOn(logger, 'warn').mockImplementation((() => logger) as any);
+    jest.spyOn(logger, 'error').mockImplementation((() => logger) as any);
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  it('logs at warn when TFSServices already reported the error', () => {
+    const err = annotateAdoError(new Error('x'), { method: 'GET', url: 'https://h/y', reported: true });
+    logCaughtError('Could not fetch Y:', err);
+    expect(logger.warn).toHaveBeenCalledWith('Could not fetch Y:', expect.objectContaining({ message: 'x' }));
+    expect(logger.error).not.toHaveBeenCalled();
+  });
+
+  it('stays at error when the error was annotated but not reported (printError=false)', () => {
+    const err = annotateAdoError(new Error('x'), { method: 'GET', url: 'https://h/y', reported: false });
+    logCaughtError('Could not fetch Y:', err);
+    expect(logger.error).toHaveBeenCalledTimes(1);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it('stays at error for a non-ADO error', () => {
+    logCaughtError('Could not fetch Y:', new Error('plain'));
+    expect(logger.error).toHaveBeenCalledTimes(1);
+  });
+});

package/src/tests/helpers/tfs.test.ts

@@ -1089,3 +1089,110 @@ describe('TFSServices', () => {
     });
   });
 });
+
+describe('TFSServices request-context annotation', () => {
+  // Math.random is pinned and setTimeout collapsed so a retried failure doesn't slow the suite.
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockAxiosInstance.request.mockReset();
+  });
+
+  const notFound = () => {
+    const e: any = new Error('Request failed with status code 404');
+    e.response = { status: 404, data: { message: 'TF401232: Work item 5 does not exist' } };
+    return e;
+  };
+
+  it('annotates the thrown error with the request even when printError is false, without logging', async () => {
+    mockAxiosInstance.request.mockRejectedValue(notFound());
+
+    const caught = await TFSServices.getItemContent('https://dev.azure.com/org/_apis/wit/queries/q1', 'pat', 'get', {}, {}, false).catch(
+      (e) => e
+    );
+
+    expect(caught.adoRequest).toEqual({
+      method: 'GET',
+      url: 'https://dev.azure.com/org/_apis/wit/queries/q1',
+      status: 404,
+      attempt: 1,
+      reported: false,
+      responseExcerpt: 'TF401232: Work item 5 does not exist',
+    });
+    expect(logger.error).not.toHaveBeenCalled();
+  });
+
+  it('with printError, also emits the one "ADO request failed" record carrying the same context', async () => {
+    mockAxiosInstance.request.mockRejectedValue(notFound());
+
+    await TFSServices.getItemContent('https://dev.azure.com/org/_apis/x', 'pat').catch(() => undefined);
+
+    expect(logger.error).toHaveBeenCalledTimes(1);
+    expect(logger.error).toHaveBeenCalledWith(
+      'ADO request failed: GET /org/_apis/x -> 404',
+      expect.objectContaining({
+        adoRequest: expect.objectContaining({
+          method: 'GET',
+          url: 'https://dev.azure.com/org/_apis/x',
+          status: 404,
+          reported: true,
+        }),
+      })
+    );
+  });
+
+  it('puts status and templated path in the message so 401 and 404 group separately', async () => {
+    const e401: any = new Error('Request failed with status code 401');
+    e401.response = { status: 401, data: {} };
+    mockAxiosInstance.request.mockRejectedValueOnce(e401);
+    await TFSServices.getItemContent('https://dev.azure.com/org/p/_apis/wit/workitems/123', 'pat').catch(() => undefined);
+    mockAxiosInstance.request.mockRejectedValueOnce(notFound());
+    await TFSServices.getItemContent('https://dev.azure.com/org/p/_apis/wit/workitems/456', 'pat').catch(() => undefined);
+
+    const messages = (logger.error as jest.Mock).mock.calls.map((c) => c[0]);
+    expect(messages).toEqual([
+      'ADO request failed: GET /org/p/_apis/wit/workitems/{id} -> 401',
+      'ADO request failed: GET /org/p/_apis/wit/workitems/{id} -> 404',
+    ]);
+  });
+
+  it('never leaks the PAT: credentials are applied to the axios config, not the description', async () => {
+    mockAxiosInstance.request.mockRejectedValue(notFound());
+
+    const caught = await TFSServices.getItemContent('https://dev.azure.com/org/_apis/x', 'super-secret-pat', 'get', {}, {}, false).catch(
+      (e) => e
+    );
+
+    expect(JSON.stringify(caught.adoRequest)).not.toContain('super-secret-pat');
+  });
+
+  it('postRequest describes a JSON-Patch body by op + path only', async () => {
+    mockAxiosInstance.request.mockRejectedValue(notFound());
+
+    const caught = await TFSServices.postRequest(
+      'https://dev.azure.com/org/_apis/wit/workitems/9',
+      'pat',
+      'PATCH',
+      [{ op: 'add', path: '/fields/System.Title', value: 'confidential title' }]
+    ).catch((e) => e);
+
+    expect(caught.adoRequest.method).toBe('PATCH');
+    expect(caught.adoRequest.requestBody).toContain('add /fields/System.Title');
+    expect(caught.adoRequest.requestBody).not.toContain('confidential');
+  });
+
+  it('getJfrogRequest annotates too', async () => {
+    mockAxiosInstance.request.mockRejectedValue(notFound());
+
+    const caught = await TFSServices.getJfrogRequest('https://jfrog.example/api/x').catch((e) => e);
+
+    expect(caught.adoRequest).toEqual(expect.objectContaining({ method: 'GET', url: 'https://jfrog.example/api/x', status: 404 }));
+  });
+
+  it('downloadZipFile annotates the error it rethrows', async () => {
+    mockAxiosInstance.request.mockRejectedValue(notFound());
+
+    const caught = await TFSServices.downloadZipFile('https://dev.azure.com/org/file.zip', 'pat').catch((e) => e);
+
+    expect(caught.adoRequest).toEqual(expect.objectContaining({ method: 'GET', url: 'https://dev.azure.com/org/file.zip', status: 404 }));
+  });
+});

package/src/tests/modules/JfrogDataProvider.test.ts

@@ -162,7 +162,8 @@ describe('JfrogDataProvider', () => {
       ).rejects.toThrow('JFrog API error');
 
       expect(logger.error).toHaveBeenCalledWith(
-        `Error occurred during querying JFrog using: JFrog API error`
+        'Error occurred during querying JFrog using:',
+        expect.objectContaining({ message: 'JFrog API error' })
       );
     });
   });

package/src/tests/modules/ResultDataProvider.test.ts

@@ -5324,7 +5324,8 @@ describe('ResultDataProvider', () => {
       );
 
       expect(logger.error).toHaveBeenCalledWith(
-        expect.stringContaining('Could not append related work item to test case 999')
+        'Could not append related work item to test case 999:',
+        expect.objectContaining({ message: 'network' })
       );
     });
   });
@@ -6029,7 +6030,10 @@ describe('ResultDataProvider', () => {
 
       // Was two separate calls (message, then the response body) — consolidated into one
       // record with the response summary as meta (docgen-log-redaction / Phase 2/4).
-      expect(logger.error).toHaveBeenCalledWith('Error during getCombinedResultsSummary: boom', {
+      expect(logger.error).toHaveBeenCalledWith('Error during getCombinedResultsSummary:', {
+        message: 'boom',
+        errMessage: 'boom',
+        stack: expect.any(String),
         responseSummary: '{"detail":"bad"}',
       });
       expect(logger.error).toHaveBeenCalledTimes(1);

package/src/tests/modules/gitDataProvider.test.ts

@@ -367,7 +367,8 @@ describe('GitDataProvider - GetFileFromGitRepo', () => {
 
     // Assert
     expect(logger.warn).toHaveBeenCalledWith(
-      expect.stringContaining(`File ${mockFileName} could not be read: ${mockError.message}`)
+      `File ${mockFileName} could not be read:`,
+      expect.objectContaining({ message: mockError.message })
     );
     expect(result).toBeUndefined();
   });

package/src/tests/modules/pipelineDataProvider.test.ts

@@ -305,7 +305,8 @@ describe('PipelinesDataProvider', () => {
         null
       );
       expect(logger.error).toHaveBeenCalledWith(
-        `Could not fetch Pipeline Run History: ${expectedError.message}`
+        'Could not fetch Pipeline Run History:',
+        expect.objectContaining({ message: expectedError.message })
       );
       expect(result).toBeUndefined();
     });

package/src/tests/modules/testDataProvider.test.ts

@@ -105,7 +105,10 @@ describe('TestDataProvider', () => {
 
       // Act & Assert
       await expect(invokeFetchWithCache(testDataProvider, mockUrl)).rejects.toThrow('API call failed');
-      expect(logger.error).toHaveBeenCalledWith(`Error fetching ${mockUrl}: API call failed`);
+      expect(logger.error).toHaveBeenCalledWith(
+        `Error fetching ${mockUrl}:`,
+        expect.objectContaining({ message: 'API call failed' })
+      );
     });
   });
 

package/src/tests/modules/ticketsDataProvider.test.ts

@@ -1108,7 +1108,7 @@ describe('TicketsDataProvider', () => {
       expect(() =>
         (ticketsDataProvider as any).filterFieldsByColumns(item, columnsToFilterMap, resultedRefNameMap),
       ).toThrow();
-      expect(logger.error).toHaveBeenCalledWith(expect.stringContaining('Cannot filter columns'));
+      expect(logger.error).toHaveBeenCalledWith('Cannot filter columns:', expect.objectContaining({ message: expect.any(String) }));
     });
   });
 
@@ -2779,7 +2779,7 @@ describe('TicketsDataProvider', () => {
       expect(res.categories['Security and Privacy Requirements']).toHaveLength(1);
       expect(res.categories['Precedence and Criticality of Requirements']).toHaveLength(1);
       expect(res.categories['Other Requirements']).toHaveLength(1);
-      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('Could not fetch work item 13'));
+      expect(logger.warn).toHaveBeenCalledWith('Could not fetch work item 13:', expect.objectContaining({ message: 'boom' }));
     });
 
     it('should extract IDs from workItemRelations for OneHop queries', async () => {

package/src/tests/utils/logger.test.ts

@@ -1,6 +1,6 @@
 import * as winston from 'winston';
 import Transport = require('winston-transport');
-import { redact, DiagnosticsTransport } from '../../utils/logger';
+import { redact, DiagnosticsTransport, isSensitiveKey, skipUncaptured } from '../../utils/logger';
 import { installLogSink, LogSink, DiagnosticEvent } from '../../utils/logSink';
 import { runContextStore } from '../../utils/runContext';
 
@@ -169,6 +169,117 @@ describe('DiagnosticsTransport (Phase 6a)', () => {
   });
 });
 
+describe('DiagnosticsTransport request context', () => {
+  function makeLogger() {
+    return winston.createLogger({
+      level: 'silly',
+      format: winston.format.combine(
+        winston.format.errors({ stack: true }),
+        winston.format.timestamp(),
+        redact(),
+        winston.format.splat(),
+        winston.format.json()
+      ),
+      transports: [new DiagnosticsTransport()],
+    });
+  }
+
+  test('persists an annotated error\'s request as event.context, however the call site words its message', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    const err = Object.assign(new Error('Request failed with status code 404'), {
+      adoRequest: { method: 'GET', url: 'https://dev.azure.com/org/_apis/x', status: 404, attempt: 1, responseExcerpt: 'nope' },
+    });
+
+    makeLogger().error(err); // the bare-error shape (3 call sites) — no stable message at all
+
+    expect(events[0].context).toEqual({
+      method: 'GET',
+      url: 'https://dev.azure.com/org/_apis/x',
+      status: 404,
+      attempt: 1,
+      responseExcerpt: 'nope',
+    });
+  });
+
+  test('also works for the stable-message + error shape and for the explicit meta shape', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    const logger = makeLogger();
+    const ctx = { method: 'POST', url: 'https://h/wiql', requestBody: '{"query":"q"}' };
+
+    logger.error('Failed querying work items', Object.assign(new Error('boom'), { adoRequest: ctx }));
+    logger.error('ADO request failed', { message: 'boom', stack: 'at x', adoRequest: ctx });
+
+    expect(events[0].context).toEqual(ctx);
+    expect(events[1].context).toEqual(ctx);
+  });
+
+  test('an event with no request context has no context field', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    makeLogger().error('plain failure', new Error('boom'));
+    expect(events[0].context).toBeUndefined();
+  });
+
+  test('re-validates the shape at the transport: unknown keys, wrong types and oversize values are dropped or bounded', () => {
+    const events: DiagnosticEvent[] = [];
+    installLogSink({ push: (e) => events.push(e) });
+    const err = Object.assign(new Error('x'), {
+      adoRequest: {
+        method: 'GET',
+        url: 'u'.repeat(5000),
+        status: 'not-a-number',
+        attempt: 2,
+        requestBody: 'b'.repeat(5000),
+        secretHeader: 'Bearer abc',
+      },
+    });
+
+    makeLogger().error('m', err);
+
+    const ctx = events[0].context!;
+    expect(ctx.url!.length).toBe(1000);
+    expect(ctx.requestBody!.length).toBe(2000);
+    expect(ctx.status).toBeUndefined();
+    expect(ctx.attempt).toBe(2);
+    expect(ctx).not.toHaveProperty('secretHeader');
+  });
+});
+
+describe('text format request suffix', () => {
+  // The default (LOG_FORMAT unset) prints only the message — without this the URL would never
+  // reach stdout for a record whose own message doesn't carry it. A stream transport on the
+  // real logger receives the already-formatted line, independent of how jest wires console.
+  test('appends the request to the printed line when the error carries one, and never throws', () => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const logger = require('../../utils/logger').default;
+    const { Writable } = require('stream');
+    const lines: string[] = [];
+    const sink = new winston.transports.Stream({
+      stream: new Writable({
+        write(chunk: Buffer, _enc: string, cb: () => void) {
+          lines.push(chunk.toString());
+          cb();
+        },
+      }),
+    });
+    logger.add(sink);
+    try {
+      const err = Object.assign(new Error('Request failed with status code 404'), {
+        adoRequest: { method: 'GET', url: 'https://dev.azure.com/org/_apis/x', status: 404 },
+      });
+      expect(() => logger.error('Failed fetching', err)).not.toThrow();
+      expect(() => logger.error('odd', Object.assign(new Error('e'), { adoRequest: { url: 123 } }))).not.toThrow();
+    } finally {
+      logger.remove(sink);
+    }
+    const joined = lines.join('');
+    expect(joined).toContain('[GET https://dev.azure.com/org/_apis/x -> 404]');
+    expect(joined).toContain('Failed fetching');
+  });
+});
+
 describe('textFormat safety (regression)', () => {
   // The hostile-input matrix above exercises makeTestLogger()'s json() pipeline — it never
   // touched the real singleton logger's text-format branch (LOG_FORMAT's default), which is
@@ -268,3 +379,37 @@ describe('DiagnosticsTransport capture policy (Phase 6b)', () => {
     expect(events[0].message).toBe('verbose debug');
   });
 });
+
+describe('isSensitiveKey', () => {
+  it.each(['token', 'accessToken', 'x-docgen-ingest-token', 'PAT', 'pat', 'password', 'DB_PASSWORD', 'Authorization', 'minioSecretKey', 'minioAccessKey', 'apiKey', 'clientSecret', 'cookie'])(
+    'redacts %s',
+    (key) => expect(isSensitiveKey(key)).toBe(true)
+  );
+  it.each(['areaPath', 'IterationPath', 'path', 'filePath', 'patch', 'dispatch', 'compatibility', 'tokenCount', 'System.AreaPath', 'url'])(
+    'keeps %s',
+    (key) => expect(isSensitiveKey(key)).toBe(false)
+  );
+  it('redact() leaves areaPath visible but scrubs a token', () => {
+    const out = applyRedact({ message: 'm', areaPath: 'P\\Area', accessToken: 'abc' });
+    expect(out.areaPath).toBe('P\\Area');
+    expect(out.accessToken).toBe('[REDACTED]');
+  });
+});
+
+describe('skipUncaptured', () => {
+  const run = (level: string) => (skipUncaptured() as any).transform({ level, message: 'm' });
+  it('keeps what stdout prints and always keeps warn/error', () => {
+    expect(run('error')).toBeTruthy();
+    expect(run('warn')).toBeTruthy();
+    expect(run('info')).toBeTruthy();
+  });
+  it('drops debug in normal mode', () => {
+    expect(run('debug')).toBe(false);
+  });
+  it('keeps debug inside a verbose run', () => {
+    const { runContextStore } = require('../../utils/runContext');
+    runContextStore.run({ runId: 'r1', captureMode: 'verbose' }, () => {
+      expect(run('debug')).toBeTruthy();
+    });
+  });
+});

package/src/utils/logSink.ts

@@ -2,9 +2,16 @@
 
 // The one queryable-error-store event shape, emitted by DiagnosticsTransport (logger.ts).
 // This package never installs a sink itself — it only reads whatever the host process
-// (docgen-content-control's index.ts) installed. err is intentionally narrow —
-// {message, code, stack} — per the settled Phase 6 schema decision: no generic
-// extra-fields bucket.
+// (docgen-content-control's index.ts) installed. err stays narrow — {message, code, stack}.
+// `context` is the one deliberate exception to "no extra-fields bucket": a sanitized
+// description of the failed outbound request (method, url, status, attempt, request-body
+// summary, response excerpt) — without it a 404 in the dashboard can't be traced to the call
+// that produced it. A fixed, allowlisted shape, not a free-form bag.
+// Bounds for DiagnosticEvent.context. Single source for this package (requestContext.ts and the
+// logger transport); docgen-api-gate's DiagnosticsController.sanitizeContext re-validates at
+// ingest with its own copy — keep the two in step.
+export const CONTEXT_LIMITS = { method: 10, url: 1000, requestBody: 2000, responseExcerpt: 300 } as const;
+
 export interface DiagnosticEvent {
   ts: string;
   level: string;
@@ -19,6 +26,14 @@ export interface DiagnosticEvent {
   userId?: string;
   message: string;
   err?: { message: string; code?: string; stack?: string };
+  context?: {
+    method?: string;
+    url?: string;
+    status?: number;
+    attempt?: number;
+    requestBody?: string;
+    responseExcerpt?: string;
+  };
   // Phase 6b — set on a debug/info event captured under retain-on-failure. Deleted by
   // api-gate at the run's one success point; left alone (and thus permanent, subject to the
   // normal TTL) if the run fails.