// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. // See LICENSE in the project root for license information. import * as fs from 'node:fs'; import * as os from 'node:os'; import * as path from 'node:path'; import { FileReporter, RUSH_LOGS_DIR_NAME, LATEST_LOG_NAME, type IFileReporterArtifact, type IReporterEventEnvelope } from '../index'; const FIXED_NOW: number = Date.UTC(2026, 6, 15, 1, 0, 0); const MS_PER_DAY: number = 24 * 60 * 60 * 1000; function ev( type: string, payload: unknown = {}, privacy: string = 'public' ): IReporterEventEnvelope { return { protocolVersion: { major: 1, minor: 0 }, eventId: 'evt', sessionId: 'sess', sequence: 1, timestamp: '2026-07-15T01:00:00.000Z', source: { packageName: '@microsoft/rush-lib', packageVersion: '5.177.2' }, privacy, required: true, type, payload } as unknown as IReporterEventEnvelope; } async function withTempDir(action: (directory: string) => Promise): Promise { const directory: string = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'rush-file-reporter-')); try { await action(directory); } finally { await fs.promises.rm(directory, { recursive: true, force: true }); } } describe('FileReporter', () => { it('preserves UTF-8 through short spool, copy, and invocation-log writes', async () => { await withTempDir(async (base: string) => { const fsModule: typeof fs = jest.requireActual('node:fs'); const originalWrite: typeof fs.writeSync = fsModule.writeSync; const reporter: FileReporter = new FileReporter({ commonTempFolder: base, nowMs: () => FIXED_NOW }); await reporter.initializeAsync(); const writeSpy = jest .spyOn(fsModule, 'writeSync') .mockImplementation( ( fd: number, data: string | NodeJS.ArrayBufferView, offset?: number | null, length?: number | BufferEncoding | null ): number => { const buffer: Buffer = typeof data === 'string' ? Buffer.from(data, 'utf8') : Buffer.from(data.buffer, data.byteOffset, data.byteLength); const start: number = typeof data === 'string' ? 0 : (offset ?? 0); const count: number = typeof length === 'number' ? length : buffer.length - start; return originalWrite(fd, buffer, start, Math.min(3, count)); } ); const text: string = 'OUTPUT-BEGIN \u{1f680} \u4e2d OUTPUT-END\n'; try { reporter.report(ev('operationRegistered', { operationId: 'op', projectName: 'project' })); reporter.report({ ...ev('externalOutput', { text }), scope: { operationId: 'op' } }); reporter.report(ev('operationCompleted', { operationId: 'op', status: 'success' })); await reporter.closeAsync(); } finally { writeSpy.mockRestore(); await reporter.closeAsync(); } const content: string = await fs.promises.readFile(reporter.getArtifact().path!, 'utf8'); expect(content).toContain('"type":"operationRegistered"'); expect(content).toContain(text); expect(content.match(/OUTPUT-BEGIN/g)).toHaveLength(1); expect(reporter.getArtifact().complete).toBe(true); }); }); it('reports a zero-progress spool failure and does not claim a complete artifact', async () => { await withTempDir(async (base: string) => { const fsModule: typeof fs = jest.requireActual('node:fs'); const warnings: string[] = []; const reporter: FileReporter = new FileReporter({ commonTempFolder: base, nowMs: () => FIXED_NOW, emergencyWarn: (warning) => warnings.push(warning) }); await reporter.initializeAsync(); reporter.report(ev('operationRegistered', { operationId: 'op', projectName: 'project' })); const writeSpy = jest.spyOn(fsModule, 'writeSync').mockReturnValueOnce(0); try { reporter.report({ ...ev('externalOutput', { text: 'RECOVERED-OUTPUT\n' }), scope: { operationId: 'op' } }); reporter.report(ev('operationCompleted', { operationId: 'op', status: 'success' })); await reporter.closeAsync(); } finally { writeSpy.mockRestore(); await reporter.closeAsync(); } expect(warnings.some((warning) => warning.includes('Unable to spool'))).toBe(true); expect(reporter.getArtifact().complete).toBe(false); const content: string = await fs.promises.readFile(reporter.getArtifact().path!, 'utf8'); expect(content.match(/RECOVERED-OUTPUT/g)).toHaveLength(1); }); }); it('recovers a failed spool suffix without repeating a partial UTF-8 prefix', async () => { await withTempDir(async (base: string) => { const fsModule: typeof fs = jest.requireActual('node:fs'); const originalWrite: typeof fs.writeSync = fsModule.writeSync; const warnings: string[] = []; const reporter: FileReporter = new FileReporter({ commonTempFolder: base, nowMs: () => FIXED_NOW, emergencyWarn: (warning) => warnings.push(warning) }); await reporter.initializeAsync(); reporter.report(ev('operationRegistered', { operationId: 'op', projectName: 'project' })); const writeSpy = jest .spyOn(fsModule, 'writeSync') .mockImplementationOnce((fd, data: string | NodeJS.ArrayBufferView) => { const buffer: Buffer = typeof data === 'string' ? Buffer.from(data, 'utf8') : Buffer.from(data.buffer, data.byteOffset, data.byteLength); return originalWrite(fd, buffer, 0, 3); }) .mockImplementationOnce(() => { throw new Error('spool full'); }); const text: string = 'A\u{1f680}B\n'; try { reporter.report({ ...ev('externalOutput', { text }), scope: { operationId: 'op' } }); reporter.report(ev('operationCompleted', { operationId: 'op', status: 'success' })); await reporter.closeAsync(); } finally { writeSpy.mockRestore(); await reporter.closeAsync(); } const content: string = await fs.promises.readFile(reporter.getArtifact().path!, 'utf8'); expect(content.split(text)).toHaveLength(2); expect(content).not.toContain('\ufffd'); expect(warnings.some((warning) => warning.includes('spool full'))).toBe(true); expect(reporter.getArtifact().complete).toBe(false); }); }); it('streams events after initialization instead of retaining the full log', async () => { await withTempDir(async (base: string) => { const reporter: FileReporter = new FileReporter({ commonTempFolder: base, nowMs: () => FIXED_NOW }); await reporter.initializeAsync(); reporter.report(ev('externalOutput', { text: 'streamed immediately' })); const content: string = await fs.promises.readFile(reporter.getArtifact().path!, 'utf8'); expect(content).toContain('streamed immediately'); await reporter.closeAsync(); }); }); it('writes a grouped full-detail log with owner-only permissions and a latest.log pointer', async () => { await withTempDir(async (base: string) => { const reporter: FileReporter = new FileReporter({ commonTempFolder: base, actionName: 'build', pid: 4242, nowMs: () => FIXED_NOW }); await reporter.initializeAsync(); reporter.report(ev('commandStarted', { commandName: 'build' })); reporter.report( ev('operationRegistered', { operationId: 'project#build', projectName: 'project', phaseName: 'build' }) ); reporter.report({ ...ev('externalOutput', { stream: 'stdout', text: 'Building...\n' }), scope: { operationId: 'project#build' } }); reporter.report(ev('operationStatusChanged', { operationId: 'project#build', status: 'success' })); reporter.report(ev('operationCompleted', { operationId: 'project#build', status: 'success' })); reporter.report(ev('commandResult', { commandName: 'build', succeeded: true, exitCode: 0 })); await reporter.closeAsync(); const artifact: IFileReporterArtifact = reporter.getArtifact(); expect(artifact.available).toBe(true); expect(artifact.complete).toBe(true); expect(artifact.path).toContain(path.join(base, RUSH_LOGS_DIR_NAME)); expect(path.basename(artifact.path!)).toBe('2026-07-15T01-00-00-000Z-4242-build.log'); const content: string = await fs.promises.readFile(artifact.path!, 'utf8'); expect(content).toContain('"type":"commandStarted"'); expect(content).toContain('==[ project (build) ]=='); expect(content).toContain('Building...\n==[ project#build: success ]=='); expect(content).toContain('"type":"commandResult"'); const latestPath: string = path.join(base, RUSH_LOGS_DIR_NAME, LATEST_LOG_NAME); expect(fs.existsSync(latestPath)).toBe(true); if (process.platform !== 'win32') { const stats: fs.Stats = await fs.promises.stat(artifact.path!); expect(stats.mode % 0o1000).toBe(0o600); } }); }); it('sanitizes action names so the log cannot escape rush-logs', async () => { await withTempDir(async (base: string) => { const reporter: FileReporter = new FileReporter({ commonTempFolder: base, actionName: 'x/../../../../victim', nowMs: () => FIXED_NOW }); await reporter.initializeAsync(); await reporter.closeAsync(); const artifactPath: string = reporter.getArtifact().path!; expect(path.dirname(artifactPath)).toBe(path.join(base, RUSH_LOGS_DIR_NAME)); expect(path.basename(artifactPath)).not.toContain('/'); }); }); it('maintains latest.log for a failed command too', async () => { await withTempDir(async (base: string) => { const reporter: FileReporter = new FileReporter({ commonTempFolder: base, actionName: 'build', nowMs: () => FIXED_NOW }); reporter.report(ev('commandResult', { commandName: 'build', succeeded: false, exitCode: 1 })); await reporter.closeAsync(); expect(fs.existsSync(path.join(base, RUSH_LOGS_DIR_NAME, LATEST_LOG_NAME))).toBe(true); }); }); it('refreshes the latest.log copy when symlinks are unavailable', async () => { await withTempDir(async (base: string) => { const symlinkSpy: jest.SpiedFunction = jest .spyOn(fs.promises, 'symlink') .mockRejectedValueOnce(new Error('symlinks unavailable')); try { const reporter: FileReporter = new FileReporter({ commonTempFolder: base, actionName: 'build', nowMs: () => FIXED_NOW }); reporter.report(ev('commandResult', { commandName: 'build', succeeded: false, exitCode: 1 })); await reporter.closeAsync(); const latestPath: string = path.join(base, RUSH_LOGS_DIR_NAME, LATEST_LOG_NAME); expect(await fs.promises.readFile(latestPath, 'utf8')).toContain('"type":"commandResult"'); } finally { symlinkSpy.mockRestore(); } }); }); it('preserves stdout and stderr chunk order while grouping parallel operations', async () => { await withTempDir(async (base: string) => { const reporter: FileReporter = new FileReporter({ commonTempFolder: base, nowMs: () => FIXED_NOW }); await reporter.initializeAsync(); for (const operationId of ['a', 'b']) { reporter.report( ev('operationRegistered', { operationId, projectName: `project-${operationId}`, phaseName: 'build' }) ); } reporter.report({ ...ev('externalOutput', { stream: 'stdout', text: 'a-out\n' }), scope: { operationId: 'a' } }); reporter.report({ ...ev('externalOutput', { stream: 'stdout', text: 'b-out\n' }), scope: { operationId: 'b' } }); reporter.report({ ...ev('externalOutput', { stream: 'stderr', text: 'a-err\n' }), scope: { operationId: 'a' } }); reporter.report(ev('operationStatusChanged', { operationId: 'a', status: 'failure' })); reporter.report(ev('operationCompleted', { operationId: 'a', status: 'failure' })); reporter.report(ev('operationStatusChanged', { operationId: 'b', status: 'blocked' })); reporter.report(ev('operationCompleted', { operationId: 'b', status: 'blocked' })); await reporter.closeAsync(); const content: string = await fs.promises.readFile(reporter.getArtifact().path!, 'utf8'); expect(content).toContain('a-out\na-err\n==[ a: failure ]=='); expect(content).toContain('b-out\n==[ b: blocked ]=='); expect(content.indexOf('a-out')).toBeLessThan(content.indexOf('a-err')); }); }); it('treats duplicate active registration as idempotent without losing spooled output', async () => { await withTempDir(async (base: string) => { const reporter: FileReporter = new FileReporter({ commonTempFolder: base, nowMs: () => FIXED_NOW }); await reporter.initializeAsync(); const registration = ev('operationRegistered', { operationId: 'duplicate', projectName: 'project', phaseName: 'build' }); reporter.report(registration); reporter.report({ ...ev('externalOutput', { stream: 'stdout', text: 'first\n' }), scope: { operationId: 'duplicate' } }); reporter.report(registration); reporter.report({ ...ev('externalOutput', { stream: 'stdout', text: 'second\n' }), scope: { operationId: 'duplicate' } }); reporter.report(ev('operationCompleted', { operationId: 'duplicate', status: 'success' })); await reporter.closeAsync(); const content: string = await fs.promises.readFile(reporter.getArtifact().path!, 'utf8'); expect(content).toContain('first\nsecond\n==[ duplicate: success ]=='); }); }); it('does not retain a file descriptor for every registered operation', async () => { await withTempDir(async (base: string) => { const reporter: FileReporter = new FileReporter({ commonTempFolder: base, nowMs: () => FIXED_NOW }); await reporter.initializeAsync(); for (let index: number = 0; index < 2000; index++) { reporter.report( ev('operationRegistered', { operationId: `operation-${index}`, projectName: `project-${index}`, phaseName: 'build' }) ); } const logsDir: string = path.join(base, RUSH_LOGS_DIR_NAME); expect((await fs.promises.readdir(logsDir)).filter((entry) => entry.endsWith('.operation'))).toEqual( [] ); await reporter.closeAsync(); }); }); it('keeps bounded persistent spool descriptors and closes each one exactly once', async () => { await withTempDir(async (base: string) => { const reporter: FileReporter = new FileReporter({ commonTempFolder: base, nowMs: () => FIXED_NOW }); await reporter.initializeAsync(); const logsDir: string = path.join(base, RUSH_LOGS_DIR_NAME); const countOpenOperationDescriptors = (): number | undefined => { const processFdFolder: string = '/proc/self/fd'; if (!fs.existsSync(processFdFolder)) { return undefined; } let count: number = 0; for (const entry of fs.readdirSync(processFdFolder)) { try { if (fs.readlinkSync(path.join(processFdFolder, entry)).endsWith('.operation')) { count++; } } catch { /* Ignore descriptors that close during enumeration. */ } } return count; }; const baselineOpenDescriptors: number | undefined = countOpenOperationDescriptors(); for (const [operationId, iterationId] of [ ['completed', 6], ['closed', 7] ] as const) { reporter.report( ev('operationRegistered', { iterationId, operationId, projectName: operationId, phaseName: 'build' }) ); reporter.report({ ...ev('externalOutput', { iterationId, stream: 'stdout', text: `${operationId}-1\n` }), scope: { operationId } }); reporter.report({ ...ev('externalOutput', { iterationId, stream: 'stdout', text: `${operationId}-2\n` }), scope: { operationId } }); } expect( (await fs.promises.readdir(logsDir)).filter((entry) => entry.endsWith('.operation')) ).toHaveLength(2); if (baselineOpenDescriptors !== undefined) { expect(countOpenOperationDescriptors()).toBe(baselineOpenDescriptors + 2); } reporter.report( ev('operationCompleted', { iterationId: 6, operationId: 'completed', status: 'success' }) ); await reporter.closeAsync(); const content: string = await fs.promises.readFile(reporter.getArtifact().path!, 'utf8'); expect(content).toContain('closed-1\nclosed-2\n==[ closed: aborted ]=='); expect(content).not.toContain('\u0000'); expect((await fs.promises.readdir(logsDir)).filter((entry) => entry.endsWith('.operation'))).toEqual( [] ); if (baselineOpenDescriptors !== undefined) { expect(countOpenOperationDescriptors()).toBe(baselineOpenDescriptors); } }); }); it('excludes secret fields but keeps local-sensitive values', async () => { await withTempDir(async (base: string) => { const reporter: FileReporter = new FileReporter({ commonTempFolder: base, nowMs: () => FIXED_NOW }); reporter.report( ev('diagnosticEmitted', { code: 'RUSH_DEPENDENCY_TOOL_FAILED', category: 'dependency-tool', severity: 'error', parameters: { token: { value: 'sk-secret-value', privacy: 'secret' }, logPath: { value: '/home/user/install.log', privacy: 'local-sensitive' } } }) ); await reporter.closeAsync(); const content: string = await fs.promises.readFile(reporter.getArtifact().path!, 'utf8'); expect(content).not.toContain('sk-secret-value'); expect(content).toContain('[secret]'); expect(content).toContain('/home/user/install.log'); }); }); it('never groups or spools secret operation values', async () => { await withTempDir(async (base: string) => { const reporter: FileReporter = new FileReporter({ commonTempFolder: base, nowMs: () => FIXED_NOW }); reporter.report( ev( 'operationRegistered', { operationId: 'secret-operation', projectName: '@secret/project', phaseName: 'secret-phase' }, 'secret' ) ); reporter.report({ ...ev('externalOutput', { stream: 'stdout', text: 'TOP_SECRET_OUTPUT' }, 'secret'), scope: { operationId: 'secret-operation' } }); reporter.report( ev('operationCompleted', { operationId: 'secret-operation', status: 'failure' }, 'secret') ); reporter.report( ev( 'operationRegistered', { operationId: 'unfinished-secret', projectName: '@secret/unfinished' }, 'secret' ) ); await reporter.closeAsync(); const content: string = await fs.promises.readFile(reporter.getArtifact().path!, 'utf8'); expect(content).toContain('[secret]'); expect(content).not.toContain('secret-operation'); expect(content).not.toContain('@secret/project'); expect(content).not.toContain('secret-phase'); expect(content).not.toContain('TOP_SECRET_OUTPUT'); expect(content).not.toContain('unfinished-secret'); expect(content).not.toContain('@secret/unfinished'); }); }); it('retains local-sensitive producer identity but redacts secret producer identity', async () => { await withTempDir(async (base: string) => { const reporter: FileReporter = new FileReporter({ commonTempFolder: base, nowMs: () => FIXED_NOW }); reporter.report({ ...ev('extension', { name: 'local.plugin.event' }, 'local-sensitive'), source: { packageName: '@private/example-rush-plugin', packageVersion: '1.0.0', component: 'PrivatePluginImplementation' } }); reporter.report({ ...ev('extension', { name: 'secret.plugin.event' }, 'secret'), source: { packageName: '@secret/example-rush-plugin', packageVersion: '2.0.0', component: 'SecretPluginImplementation' } }); await reporter.closeAsync(); const content: string = await fs.promises.readFile(reporter.getArtifact().path!, 'utf8'); expect(content).toContain('@private/example-rush-plugin'); expect(content).toContain('PrivatePluginImplementation'); expect(content).not.toContain('@secret/example-rush-plugin'); expect(content).not.toContain('SecretPluginImplementation'); expect(content).toContain('[private-producer]'); expect(content).toContain('[private-version]'); }); }); it('deletes logs older than the retention window and caps the session count', async () => { await withTempDir(async (base: string) => { const logsDir: string = path.join(base, RUSH_LOGS_DIR_NAME); await fs.promises.mkdir(logsDir, { recursive: true }); const oldLog: string = path.join(logsDir, 'old-1-build.log'); await fs.promises.writeFile(oldLog, '{}\n'); const oldSpool: string = path.join(logsDir, 'abandoned.operation'); await fs.promises.writeFile(oldSpool, 'abandoned output'); const oldTime: Date = new Date(FIXED_NOW - 20 * MS_PER_DAY); await fs.promises.utimes(oldLog, oldTime, oldTime); await fs.promises.utimes(oldSpool, oldTime, oldTime); // Create more than the cap of recent logs. for (let i: number = 0; i < 22; i++) { const recent: string = path.join(logsDir, `recent-${i}-build.log`); await fs.promises.writeFile(recent, '{}\n'); const time: Date = new Date(FIXED_NOW - (i + 1) * 1000); await fs.promises.utimes(recent, time, time); } const reporter: FileReporter = new FileReporter({ commonTempFolder: base, maxSessions: 20, nowMs: () => FIXED_NOW }); reporter.report(ev('commandResult', { commandName: 'build', succeeded: true, exitCode: 0 })); await reporter.closeAsync(); const remaining: string[] = (await fs.promises.readdir(logsDir)).filter( (name: string) => name.endsWith('.log') && name !== LATEST_LOG_NAME ); expect(remaining).not.toContain('old-1-build.log'); expect(remaining.length).toBe(20); expect(fs.existsSync(oldSpool)).toBe(false); }); }); it('falls back to the OS temp folder when the repository path fails', async () => { await withTempDir(async (base: string) => { const blocker: string = path.join(base, 'blocker'); await fs.promises.writeFile(blocker, 'not a directory'); const osTemp: string = path.join(base, 'os-temp'); await fs.promises.mkdir(osTemp); const reporter: FileReporter = new FileReporter({ commonTempFolder: blocker, osTempFolder: osTemp, nowMs: () => FIXED_NOW }); reporter.report(ev('commandResult', { commandName: 'build', succeeded: true, exitCode: 0 })); await reporter.closeAsync(); const artifact: IFileReporterArtifact = reporter.getArtifact(); expect(artifact.available).toBe(true); expect(path.dirname(artifact.path!).startsWith(path.join(osTemp, `${RUSH_LOGS_DIR_NAME}-`))).toBe(true); if (process.platform !== 'win32') { const directoryStats: fs.Stats = await fs.promises.stat(path.dirname(artifact.path!)); expect(directoryStats.mode % 0o1000).toBe(0o700); } }); }); it('treats failure at both paths as nonfatal with an emergency warning', async () => { await withTempDir(async (base: string) => { const repoBlocker: string = path.join(base, 'repo-blocker'); const osBlocker: string = path.join(base, 'os-blocker'); await fs.promises.writeFile(repoBlocker, 'file'); await fs.promises.writeFile(osBlocker, 'file'); const warnings: string[] = []; const reporter: FileReporter = new FileReporter({ commonTempFolder: repoBlocker, osTempFolder: osBlocker, nowMs: () => FIXED_NOW, emergencyWarn: (message: string) => warnings.push(message) }); reporter.report(ev('commandResult', { commandName: 'build', succeeded: true, exitCode: 0 })); await reporter.closeAsync(); expect(reporter.getArtifact().available).toBe(false); expect(warnings.some((w: string) => w.includes('artifact is unavailable'))).toBe(true); }); }); });