|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * `os migrate summary-nulls` command shape, and the #15064 scope it surfaces. |
| 5 | + * |
| 6 | + * The backfill itself is proven in `@objectstack/objectql`'s |
| 7 | + * `summary-backfill.test.ts`. What is pinned here is what a unit test of the |
| 8 | + * backfill cannot see: that the command is dry-run-by-default (#2186), and |
| 9 | + * that `--recompute-undefined-on-empty object.field` reaches |
| 10 | + * `backfillSummaryNulls` as `recomputeUndefinedOnEmpty` — every entry, in |
| 11 | + * order — while a run without the flag hands the option through as `undefined` |
| 12 | + * (the unscoped run the ruling keeps byte-for-byte). The seams that would boot |
| 13 | + * a database or walk a real engine are replaced; the command's own parse and |
| 14 | + * control flow run for real. |
| 15 | + */ |
| 16 | + |
| 17 | +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; |
| 18 | +import { dirname, resolve } from 'node:path'; |
| 19 | +import { fileURLToPath } from 'node:url'; |
| 20 | +import MigrateSummaryNulls from './summary-nulls.js'; |
| 21 | +import { bootSchemaStack } from '../../utils/schema-migrate.js'; |
| 22 | +import { probeMigrationTarget } from '../../utils/migrate-occupancy-gate.js'; |
| 23 | +import { isExitSignal } from '../../utils/format.js'; |
| 24 | +import { backfillSummaryNulls } from '@objectstack/objectql'; |
| 25 | + |
| 26 | +vi.mock('../../utils/schema-migrate.js', () => ({ bootSchemaStack: vi.fn() })); |
| 27 | +vi.mock('../../utils/migrate-occupancy-gate.js', () => ({ |
| 28 | + OCCUPANCY_HINT: 'occupancy hint', |
| 29 | + probeMigrationTarget: vi.fn(), |
| 30 | +})); |
| 31 | +vi.mock('../../utils/data-migration-plugins.js', () => ({ buildDataMigrationPlugins: vi.fn(async () => []) })); |
| 32 | +vi.mock('@objectstack/objectql', () => ({ |
| 33 | + backfillSummaryNulls: vi.fn(), |
| 34 | + formatSummaryBackfillReport: vi.fn(() => []), |
| 35 | +})); |
| 36 | + |
| 37 | +const HERE = dirname(fileURLToPath(import.meta.url)); |
| 38 | +const CLI_ROOT = resolve(HERE, '..', '..', '..'); |
| 39 | +/** oclif builds its whole command table on the first `run()` in a process. */ |
| 40 | +const RUN_TIMEOUT = 60_000; |
| 41 | + |
| 42 | +/** The engine surface the command checks before it runs: the roll-up index |
| 43 | + * verb, and at least one loaded app object (a `sys_`-only stack is refused). */ |
| 44 | +const engine = { |
| 45 | + getOwnedSummaryDescriptors: () => [], |
| 46 | + getConfigs: () => ({ customer: {}, sys_user: {} }), |
| 47 | +}; |
| 48 | + |
| 49 | +const EMPTY_REPORT = { |
| 50 | + scannedObjects: [], scannedRecords: 0, fields: [], nullRows: 0, filled: 0, |
| 51 | + skippedUndefinedOnEmpty: [], recomputedUndefinedOnEmpty: [], applied: false, |
| 52 | + truncated: false, unreadableObjects: [], failures: [], |
| 53 | +}; |
| 54 | + |
| 55 | +let stdout: ReturnType<typeof vi.spyOn>; |
| 56 | +let log: ReturnType<typeof vi.spyOn>; |
| 57 | +beforeEach(() => { |
| 58 | + vi.mocked(probeMigrationTarget).mockResolvedValue({ status: 'free' } as any); |
| 59 | + vi.mocked(bootSchemaStack).mockResolvedValue({ |
| 60 | + kernel: { getService: () => engine }, |
| 61 | + dbLabel: 'file:test.db', |
| 62 | + shutdown: vi.fn(async () => {}), |
| 63 | + } as any); |
| 64 | + vi.mocked(backfillSummaryNulls).mockReset(); |
| 65 | + vi.mocked(backfillSummaryNulls).mockResolvedValue(EMPTY_REPORT as any); |
| 66 | + // `emitJson` awaits the write's DRAIN callback (a `--json` payload must be |
| 67 | + // fully written before the process can exit), so the double has to invoke |
| 68 | + // it — a bare `() => true` hangs the command forever. |
| 69 | + stdout = vi.spyOn(process.stdout, 'write').mockImplementation(((chunk: unknown, enc?: unknown, cb?: unknown) => { |
| 70 | + const done = typeof enc === 'function' ? enc : cb; |
| 71 | + if (typeof done === 'function') done(); |
| 72 | + return true; |
| 73 | + }) as typeof process.stdout.write); |
| 74 | + log = vi.spyOn(console, 'log').mockImplementation(() => {}); |
| 75 | +}); |
| 76 | +afterEach(() => { |
| 77 | + stdout.mockRestore(); |
| 78 | + log.mockRestore(); |
| 79 | +}); |
| 80 | + |
| 81 | +const optionsHandedToBackfill = () => { |
| 82 | + expect(vi.mocked(backfillSummaryNulls)).toHaveBeenCalledTimes(1); |
| 83 | + const options = vi.mocked(backfillSummaryNulls).mock.calls[0][2]; |
| 84 | + expect(options).toBeDefined(); |
| 85 | + return options!; |
| 86 | +}; |
| 87 | + |
| 88 | +describe('os migrate summary-nulls', () => { |
| 89 | + it('is a dry run by default — --apply is opt-in (#2186)', () => { |
| 90 | + expect(MigrateSummaryNulls.flags.apply.default).toBe(false); |
| 91 | + }); |
| 92 | + |
| 93 | + it('requires explicit confirmation to write — --yes is opt-in', () => { |
| 94 | + expect(MigrateSummaryNulls.flags.yes.default).toBe(false); |
| 95 | + }); |
| 96 | + |
| 97 | + it('declares --recompute-undefined-on-empty as a repeatable object.field list, and shows it in --help', () => { |
| 98 | + const flag = MigrateSummaryNulls.flags['recompute-undefined-on-empty']; |
| 99 | + expect(flag.multiple).toBe(true); |
| 100 | + expect(flag.description).toContain('object.field'); |
| 101 | + expect(flag.description).toMatch(/min\/max\/avg/); |
| 102 | + expect(flag.description).toContain('never computed'); |
| 103 | + expect(MigrateSummaryNulls.examples).toEqual( |
| 104 | + expect.arrayContaining([expect.stringContaining('--recompute-undefined-on-empty customer.last_follow_up_at')]), |
| 105 | + ); |
| 106 | + }); |
| 107 | + |
| 108 | + it('hands every --recompute-undefined-on-empty entry to backfillSummaryNulls as recomputeUndefinedOnEmpty, in order (#15064)', async () => { |
| 109 | + await MigrateSummaryNulls.run([ |
| 110 | + '--json', |
| 111 | + '--object', 'customer', |
| 112 | + '--recompute-undefined-on-empty', 'customer.last_follow_up_at', |
| 113 | + '--recompute-undefined-on-empty', 'customer.first_follow_up_at', |
| 114 | + ], { root: CLI_ROOT }); |
| 115 | + |
| 116 | + expect(optionsHandedToBackfill()).toEqual({ |
| 117 | + apply: false, |
| 118 | + objects: ['customer'], |
| 119 | + recomputeUndefinedOnEmpty: ['customer.last_follow_up_at', 'customer.first_follow_up_at'], |
| 120 | + maxRecordsPerObject: undefined, |
| 121 | + }); |
| 122 | + }, RUN_TIMEOUT); |
| 123 | + |
| 124 | + it('without the flag the option is absent — the unscoped run the ruling keeps as it was', async () => { |
| 125 | + await MigrateSummaryNulls.run(['--json'], { root: CLI_ROOT }); |
| 126 | + |
| 127 | + const options = optionsHandedToBackfill(); |
| 128 | + expect(options.recomputeUndefinedOnEmpty).toBeUndefined(); |
| 129 | + expect(options).toEqual({ apply: false, objects: undefined, recomputeUndefinedOnEmpty: undefined, maxRecordsPerObject: undefined }); |
| 130 | + }, RUN_TIMEOUT); |
| 131 | + |
| 132 | + it('a refused scope entry (INVALID_FIELD) reaches the --json error envelope with its code, and the command exits 1', async () => { |
| 133 | + const refusal = Object.assign(new Error('[summary-backfill] recomputeUndefinedOnEmpty names 1 roll-up(s) this run cannot find: customer.nope.'), { |
| 134 | + code: 'INVALID_FIELD', status: 400, field: 'customer.nope', fields: ['customer.nope'], |
| 135 | + }); |
| 136 | + vi.mocked(backfillSummaryNulls).mockRejectedValue(refusal); |
| 137 | + |
| 138 | + const err = await MigrateSummaryNulls.run( |
| 139 | + ['--json', '--recompute-undefined-on-empty', 'customer.nope'], |
| 140 | + { root: CLI_ROOT }, |
| 141 | + ).catch((e: unknown) => e); |
| 142 | + |
| 143 | + expect(isExitSignal(err)).toBe(true); |
| 144 | + expect((err as { oclif?: { exit?: number } }).oclif?.exit).toBe(1); |
| 145 | + const emitted = stdout.mock.calls.map((c: unknown[]) => String(c[0])).join(''); |
| 146 | + const payload = JSON.parse(emitted); |
| 147 | + expect(payload).toMatchObject({ code: 'INVALID_FIELD' }); |
| 148 | + expect(payload.error).toContain('customer.nope'); |
| 149 | + }, RUN_TIMEOUT); |
| 150 | +}); |
0 commit comments