From 8adf22b0ba3d0cce85513d9399a71069bebdee04 Mon Sep 17 00:00:00 2001 From: thomasbeaudry Date: Mon, 16 Nov 2026 16:03:38 -0500 Subject: [PATCH] fix: report what a repository sync actually did MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four ways the instrument repository pages disagreed with the sync behind them. An import that discovered no instrument directories was recorded as a success with 0 imported. A repository laid out any other way downloads cleanly and yields nothing, so that entry was indistinguishable from a genuinely empty repository, against the rule that nothing fails silently. `importInstruments` now refuses it, naming the four `lib/*` directories it looked in and what it looked for, so the entry reads FAILED with an actionable reason and adding such a repository fails up front rather than registering it with nothing in it. A sync no longer replaces the stored instrument list unless it matched something. Every instrument failing to load — a bad upstream commit, a series whose member edition is gone — is not evidence that the repository provides nothing, and writing an empty list would de-list instruments that are still stored and still assignable. The entry records each failure, so such a pass is reported rather than hidden. The repositories page counted and listed instruments by `sourceRepoId`, which records which import created an instrument, while the activity log counted `instrumentIds`, which is what the repository provides. The two differ for every instrument already stored when the repository was registered: the import recovers its id from the conflict and counts it, but leaves its provenance alone. A repository could report 22 imported and list 12. Both the count and the dialog now resolve the ids the repository provides through one function, so neither can drift from the other, and an id whose instrument was since deleted is in neither. The activity log recorded only the total, so an import of instruments already present read as 22 new. A sync now also records how many it created, and the Imported cell reads `22 (12 new)` with the whole split on hover. The field is nullable because Mongo has no migration: an entry written before this has no count, which is not zero. An entry that imported nothing reads as the bare total, since a run that stored nothing has no split to show. The status itself consulted neither count: a repository-level message read as a failure and any instrument failure as a partial success. A readable repository whose every instrument fails to compile or load records no message and nothing imported, so the log announced "Partial success" beside an imported count of 0. A partial success needs a part that succeeded, so such an entry now reads FAILED, while one that stored some of its instruments and skipped others still reads PARTIAL. Co-Authored-By: Claude Opus 5 --- apps/api/prisma/schema.prisma | 1 + .../instrument-repos.service.test.ts | 97 ++++++++++++++++++- .../instrument-repos.service.ts | 71 ++++++++------ .../suites/06-instrument-repo-readd.suite.ts | 21 +++- .../InstrumentRepoSyncLogTable.tsx | 37 ++++++- .../InstrumentRepoSyncLogTable.test.tsx | 47 +++++++++ .../instrument-repos/__tests__/index.test.tsx | 72 +++++++++----- .../_app/admin/instrument-repos/index.tsx | 44 ++++----- apps/web/src/utils/instrument-repo-sync.ts | 12 ++- .../__tests__/instrument-repo.test.ts | 23 ++++- .../src/instrument-repo/instrument-repo.ts | 7 ++ .../src/specs/admin-instrument-repos.spec.ts | 50 ++++++++++ 12 files changed, 391 insertions(+), 91 deletions(-) diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma index 9fcfa44f0..fa8598208 100644 --- a/apps/api/prisma/schema.prisma +++ b/apps/api/prisma/schema.prisma @@ -281,6 +281,7 @@ model InstrumentRepoSyncLog { updatedAt DateTime @updatedAt @db.Date id String @id @default(auto()) @map("_id") @db.ObjectId action InstrumentRepoSyncAction + createdCount Int? failures InstrumentRepoSyncFailure[] importedCount Int message String? diff --git a/apps/api/src/instrument-repos/__tests__/instrument-repos.service.test.ts b/apps/api/src/instrument-repos/__tests__/instrument-repos.service.test.ts index b0225f2e9..0789f4a44 100644 --- a/apps/api/src/instrument-repos/__tests__/instrument-repos.service.test.ts +++ b/apps/api/src/instrument-repos/__tests__/instrument-repos.service.test.ts @@ -251,6 +251,7 @@ describe('InstrumentReposService', () => { expect(instrumentRepoModel.create).not.toHaveBeenCalled(); expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data).toStrictEqual({ action: 'IMPORT', + createdCount: 0, failures: [], importedCount: 0, message: 'Repository not found', @@ -269,6 +270,7 @@ describe('InstrumentReposService', () => { expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data).toStrictEqual({ action: 'IMPORT', + createdCount: 0, failures, importedCount: 1, message: null, @@ -517,6 +519,7 @@ describe('InstrumentReposService', () => { it.each([ ['action', [{ action: 'asc' }]], + ['createdCount', [{ createdCount: 'asc' }]], ['failedCount', [{ failures: { _count: 'asc' } }]], ['importedCount', [{ importedCount: 'asc' }]], ['repoName', [{ repoName: 'asc' }]], @@ -763,7 +766,7 @@ describe('InstrumentReposService', () => { }); it('should request the main branch zipball from the GitHub API with the repo token', async () => { - fetchMock.mockResolvedValueOnce(await zipball({})); + fetchMock.mockResolvedValueOnce(await zipball(instrumentFiles('forms', 'A'))); await service.create({ accessToken: 'repo-token', url }); @@ -773,7 +776,7 @@ describe('InstrumentReposService', () => { it('should fall back to the server-wide token when the repo has none', async () => { configService.get.mockReturnValue('server-token'); - fetchMock.mockResolvedValueOnce(await zipball({})); + fetchMock.mockResolvedValueOnce(await zipball(instrumentFiles('forms', 'A'))); await service.create({ url }); @@ -782,7 +785,7 @@ describe('InstrumentReposService', () => { }); it('should send no authorization header when no token is configured', async () => { - fetchMock.mockResolvedValueOnce(await zipball({})); + fetchMock.mockResolvedValueOnce(await zipball(instrumentFiles('forms', 'A'))); await service.create({ url }); @@ -882,6 +885,94 @@ describe('InstrumentReposService', () => { expect(instrumentModel.update).not.toHaveBeenCalled(); }); + it('should refuse a repository that provides no instrument directories, rather than import nothing', async () => { + fetchMock.mockResolvedValueOnce(await zipball({ 'public/forms/A/index.ts': "export default 'A';" })); + + await expect(service.create({ url })).rejects.toThrow( + 'Found no instruments in owner/repo. An instrument is a directory holding an index.ts, index.tsx, index.js or index.jsx file, within lib/file, lib/forms, lib/interactive, lib/series at the root of the repository.' + ); + expect(instrumentRepoModel.create).not.toHaveBeenCalled(); + }); + + it('should log an empty repository as a failure, so it is not indistinguishable from a clean import', async () => { + fetchMock.mockResolvedValueOnce(await zipball({ 'README.md': '# repo' })); + + await expect(service.create({ url })).rejects.toThrow('Found no instruments in owner/repo'); + + expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data).toMatchObject({ + createdCount: 0, + failures: [], + importedCount: 0, + message: expect.stringContaining('Found no instruments in owner/repo') + }); + }); + + // The refusal runs on a sync too, where returning before the update is what keeps a repository's + // instruments listed: replacing the id list with nothing would de-list every one of them. + it('should keep the instruments a registered repository provides when a sync finds none', async () => { + instrumentRepoModel.findFirst.mockResolvedValueOnce({ + accessToken: null, + id: 'r1', + instrumentIds: ['stored'], + name: 'repo', + owner: 'owner', + repoName: 'repo' + }); + fetchMock.mockResolvedValueOnce(await zipball({ 'README.md': '# repo' })); + + await expect(service.sync('r1')).rejects.toThrow('Found no instruments in owner/repo'); + + expect(instrumentRepoModel.update).not.toHaveBeenCalled(); + expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data).toMatchObject({ + action: 'SYNC', + createdCount: 0, + importedCount: 0, + message: expect.stringContaining('Found no instruments in owner/repo'), + repoId: 'r1' + }); + }); + + // A readable repository whose every instrument fails is not a repository that provides none, so the + // stored list stands rather than being replaced with nothing. + it('should keep the stored instrument list when a sync matches none of what it found', async () => { + instrumentRepoModel.findFirst.mockResolvedValueOnce({ + accessToken: null, + id: 'r1', + instrumentIds: ['stored'], + name: 'repo', + owner: 'owner', + repoName: 'repo' + }); + fetchMock.mockResolvedValueOnce(await zipball(instrumentFiles('forms', 'A'))); + instrumentsService.create.mockRejectedValueOnce(new UnprocessableEntityException('details.title: Required')); + + await service.sync('r1'); + + expect(instrumentRepoModel.update).not.toHaveBeenCalled(); + expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data).toMatchObject({ + createdCount: 0, + importedCount: 0, + message: null + }); + expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data.failures).toHaveLength(1); + }); + + it('should count only the instruments it stored as created, so ones already present are not reported as new', async () => { + fetchMock.mockResolvedValueOnce( + await zipball({ ...instrumentFiles('forms', 'A'), ...instrumentFiles('forms', 'B') }) + ); + instrumentsService.create + .mockResolvedValueOnce({ id: 'created' }) + .mockRejectedValueOnce(new ConflictException("Instrument with ID 'existing' already exists!")); + + await service.create({ url }); + + expect(instrumentRepoSyncLogModel.create.mock.lastCall?.[0].data).toMatchObject({ + createdCount: 1, + importedCount: 2 + }); + }); + it('should record a conflict that does not name the existing instrument as a failure', async () => { const message = 'An instrument with the same title already exists'; fetchMock.mockResolvedValueOnce(await zipball(instrumentFiles('forms', 'A'))); diff --git a/apps/api/src/instrument-repos/instrument-repos.service.ts b/apps/api/src/instrument-repos/instrument-repos.service.ts index c8364c6ff..b356e22af 100644 --- a/apps/api/src/instrument-repos/instrument-repos.service.ts +++ b/apps/api/src/instrument-repos/instrument-repos.service.ts @@ -56,6 +56,7 @@ const getSyncLogOrderBy = ( const orderBy = { action: [{ action: sortOrder }], createdAt: [{ createdAt: sortOrder }], + createdCount: [{ createdCount: sortOrder }], failedCount: [{ failures: { _count: sortOrder } }], importedCount: [{ importedCount: sortOrder }], repoName: [{ repoName: sortOrder }], @@ -64,6 +65,15 @@ const getSyncLogOrderBy = ( return [...orderBy, { id: 'desc' as const }]; }; +/** + * The directories a repository may provide instruments in, relative to its root. `series` is scanned + * last, and callers must import in that order: a series is rejected unless every instrument it + * references is already stored, so the scalars a repo provides have to be created first. A series + * referencing a *different* repo still fails; see + * `.agents/docs/architecture/instrument-pipeline.md`. + */ +const INSTRUMENT_CATEGORIES = ['file', 'forms', 'interactive', 'series'] as const; + const $ExceptionDetails = z.object({ cause: z.object({ message: z.string() }).optional(), issues: z.array(z.object({ message: z.string(), path: z.array(z.union([z.string(), z.number()])) })).optional() @@ -131,7 +141,7 @@ export class InstrumentReposService implements OnModuleInit { await this.recordSync({ action: 'IMPORT', error: err, repoId: null, repoName }); throw err; } - const { createdIds, failures, instrumentIds } = result; + const { createdIds, instrumentIds } = result; const repo = await this.instrumentRepoModel.create({ data: { @@ -148,13 +158,7 @@ export class InstrumentReposService implements OnModuleInit { // Attribute provenance only to instruments this import actually created. Instruments that // already existed (e.g. added manually) keep their original provenance. await this.tagInstruments(createdIds, repo.id, repo.name); - await this.recordSync({ - action: 'IMPORT', - failures, - importedCount: instrumentIds.length, - repoId: repo.id, - repoName - }); + await this.recordSync({ action: 'IMPORT', repoId: repo.id, repoName, result }); // Re-adopt any pre-existing instruments orphaned by a previously-deleted copy of this repo. await this.reconcileOrphanedInstruments(); @@ -294,11 +298,7 @@ export class InstrumentReposService implements OnModuleInit { private discoverInstrumentDirs(repoDir: string): string[] { const dirs: string[] = []; - // `series` is scanned last, and callers must import in the returned order: a series is rejected - // unless every instrument it references is already stored, so the scalars a repo provides have to - // be created first. A series referencing a *different* repo still fails; see - // `.agents/docs/architecture/instrument-pipeline.md`. - for (const category of ['file', 'forms', 'interactive', 'series']) { + for (const category of INSTRUMENT_CATEGORIES) { const libDir = path.join(repoDir, 'lib', category); if (!fs.existsSync(libDir)) { continue; @@ -453,6 +453,15 @@ export class InstrumentReposService implements OnModuleInit { const instrumentDirs = this.discoverInstrumentDirs(repoDir); this.loggingService.log(`Found ${instrumentDirs.length} instrument directories in ${owner}/${repoName}`); + // Importing nothing is a failure, not an empty success: a repository laid out any other way + // downloads cleanly and yields no directories, and a log reading "0 imported" with nothing wrong + // gives no way to tell that apart from a repository that is genuinely empty. + if (instrumentDirs.length === 0) { + throw new BadGatewayException( + `Found no instruments in ${owner}/${repoName}. An instrument is a directory holding an index.ts, index.tsx, index.js or index.jsx file, within ${INSTRUMENT_CATEGORIES.map((category) => `lib/${category}`).join(', ')} at the root of the repository.` + ); + } + // instrumentIds: every instrument the repo provides; createdIds: only those newly created here. const instrumentIds: string[] = []; const createdIds: string[] = []; @@ -581,14 +590,21 @@ export class InstrumentReposService implements OnModuleInit { private recordSync( entry: { action: InstrumentRepoSyncAction; repoId: null | string; repoName: string } & ( - { error: unknown } | { failures: InstrumentRepoSyncFailure[]; importedCount: number } + { error: unknown } | { result: RepoImportResult } ) ) { const { action, repoId, repoName } = entry; + // Counted off the import result rather than passed in beside it, so the entry cannot disagree + // with what the import actually did. const outcome = 'error' in entry - ? { failures: [], importedCount: 0, message: describeImportError(entry.error) } - : { failures: entry.failures, importedCount: entry.importedCount, message: null }; + ? { createdCount: 0, failures: [], importedCount: 0, message: describeImportError(entry.error) } + : { + createdCount: entry.result.createdIds.length, + failures: entry.result.failures, + importedCount: entry.result.instrumentIds.length, + message: null + }; return this.instrumentRepoSyncLogModel.create({ data: { action, repoId, repoName, ...outcome } }); } @@ -613,17 +629,18 @@ export class InstrumentReposService implements OnModuleInit { // Replaced rather than merged, so the list is what the repository provides now. An edition dropped // here stays in the database with its provenance tag, so groups can still see and administer it. - const updated = await this.instrumentRepoModel.update({ - data: { instrumentIds: result.instrumentIds, lastSyncedAt: new Date() }, - where: { id: repo.id } - }); - const log = await this.recordSync({ - action: 'SYNC', - failures: result.failures, - importedCount: result.instrumentIds.length, - repoId: repo.id, - repoName: repo.name - }); + // + // A pass that matched nothing is left out of that replacement. Every instrument failing to load — + // a bad upstream commit, a series whose member edition is gone — is not evidence that the + // repository provides nothing, and writing an empty list would de-list instruments that are still + // stored and still assignable. The entry records the failures, so the pass is reported, not hidden. + const updated = result.instrumentIds.length + ? await this.instrumentRepoModel.update({ + data: { instrumentIds: result.instrumentIds, lastSyncedAt: new Date() }, + where: { id: repo.id } + }) + : repo; + const log = await this.recordSync({ action: 'SYNC', repoId: repo.id, repoName: repo.name, result }); // Re-adopt any instruments that were orphaned by a previously-deleted copy of this repo. await this.reconcileOrphanedInstruments(); return { log, ok: true as const, repo: updated }; diff --git a/apps/api/test/suites/06-instrument-repo-readd.suite.ts b/apps/api/test/suites/06-instrument-repo-readd.suite.ts index 408d21932..56aceb112 100644 --- a/apps/api/test/suites/06-instrument-repo-readd.suite.ts +++ b/apps/api/test/suites/06-instrument-repo-readd.suite.ts @@ -89,9 +89,20 @@ export default defineSuite('re-adding a registered instrument repository', funct return (await prisma().instrumentRepo.findUniqueOrThrow({ where: { id } })).accessToken; }; - /** Answers every GitHub download with an empty repository, and passes any other request on. */ - const stubGitHub = async () => { - const archive = await new JSZip().generateAsync({ type: 'arraybuffer' }); + /** + * Answers every GitHub download with a repository, and passes any other request on. + * + * `providesInstrument` adds one instrument directory, which a sync that is expected to succeed + * needs: a repository providing none is refused outright. Its contents do not matter, since an + * instrument that fails to load is recorded against the sync rather than refused. The tests that + * expect a refusal leave it off, so they pay nothing for bundling an instrument no one reads. + */ + const stubGitHub = async ({ providesInstrument = false }: { providesInstrument?: boolean } = {}) => { + const zip = new JSZip(); + if (providesInstrument) { + zip.file('repo/lib/forms/example/index.ts', "export default 'example';"); + } + const archive = await zip.generateAsync({ type: 'arraybuffer' }); const realFetch = globalThis.fetch; const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation((input, init) => { return typeof input === 'string' && input.startsWith('https://api.github.com/') @@ -158,7 +169,7 @@ export default defineSuite('re-adding a registered instrument repository', funct { action: 'update', groupId: ownGroup.id, subject: 'InstrumentRepo' } ]); const repo = await registerRepo('own-group-target', [ownGroup.id]); - const fetchSpy = await stubGitHub(); + const fetchSpy = await stubGitHub({ providesInstrument: true }); const response = await reAdd(headers, repo.url); @@ -168,7 +179,7 @@ export default defineSuite('re-adding a registered instrument repository', funct it('should let an administrator replace the token and re-sync, which is how an expired one is refreshed', async () => { const repo = await registerRepo('admin-target', [otherGroup.id]); - const fetchSpy = await stubGitHub(); + const fetchSpy = await stubGitHub({ providesInstrument: true }); const response = await reAdd(adminHeaders, repo.url); diff --git a/apps/web/src/components/InstrumentRepoSyncLogTable/InstrumentRepoSyncLogTable.tsx b/apps/web/src/components/InstrumentRepoSyncLogTable/InstrumentRepoSyncLogTable.tsx index 9cf11621a..dc4e49356 100644 --- a/apps/web/src/components/InstrumentRepoSyncLogTable/InstrumentRepoSyncLogTable.tsx +++ b/apps/web/src/components/InstrumentRepoSyncLogTable/InstrumentRepoSyncLogTable.tsx @@ -60,6 +60,35 @@ const InstrumentRepoSyncLogTable = ({ LOAD: t({ en: 'Load', es: 'Carga', fr: 'Chargement' }) } satisfies { [K in InstrumentRepoSyncStage]: string }; + /** + * `importedCount` is every instrument the repository provided; `createdCount` is how many of those + * this run stored for the first time, so the remainder were already in the database. The split rides + * in this one column because the table is already as wide as the page lets it be — two more columns + * would take their room from the repository name, whose header cannot truncate. + * + * An entry that imported nothing reads as the bare total: a run that was refused outright, or whose + * every instrument failed, records a `createdCount` of zero, and `0 (0 new)` would dress a row that + * stored nothing as a split it does not have. + */ + const describeImported = ({ createdCount, importedCount }: InstrumentRepoSyncLog) => { + if (createdCount === null || createdCount === undefined || importedCount === 0) { + return { title: String(importedCount), value: String(importedCount) }; + } + const existingCount = importedCount - createdCount; + return { + title: t({ + en: `${importedCount} imported: ${createdCount} new, ${existingCount} already stored`, + es: `${importedCount} importados: ${createdCount} nuevos, ${existingCount} ya almacenados`, + fr: `${importedCount} importés : ${createdCount} nouveaux, ${existingCount} déjà stockés` + }), + value: t({ + en: `${importedCount} (${createdCount} new)`, + es: `${importedCount} (${createdCount} nuevos)`, + fr: `${importedCount} (${createdCount} nouv.)` + }) + }; + }; + /** Which import or sync the dialog is showing, since the dialog is detached from its row. */ const describeLog = (log: InstrumentRepoSyncLog) => `${log.repoName} · ${actionLabels[log.action]} · ${log.createdAt.toLocaleString()}`; @@ -161,13 +190,13 @@ const InstrumentRepoSyncLogTable = ({ /> ), id: 'status', - size: 140 + size: 124 }, { accessorKey: 'importedCount', cell: (ctx) => { - const count = String(ctx.row.original.importedCount); - return ; + const { title, value } = describeImported(ctx.row.original); + return ; }, header: ({ column }) => ( ), - size: 114 + size: 130 }, { accessorFn: (log) => log.failures.length, diff --git a/apps/web/src/components/InstrumentRepoSyncLogTable/__tests__/InstrumentRepoSyncLogTable.test.tsx b/apps/web/src/components/InstrumentRepoSyncLogTable/__tests__/InstrumentRepoSyncLogTable.test.tsx index 09726b34f..29643a3f4 100644 --- a/apps/web/src/components/InstrumentRepoSyncLogTable/__tests__/InstrumentRepoSyncLogTable.test.tsx +++ b/apps/web/src/components/InstrumentRepoSyncLogTable/__tests__/InstrumentRepoSyncLogTable.test.tsx @@ -139,6 +139,21 @@ describe('InstrumentRepoSyncLogTable', () => { expect(statuses()).toEqual(['Partial success']); }); + it('should mark a sync that imported nothing as failed, since failing every instrument is no part success', () => { + render( + + ); + expect(statuses()).toEqual(['Failed']); + }); + it('should mark a sync that could not read the repository as failed', () => { render(
); expect(statuses()).toEqual(['Failed']); @@ -240,6 +255,38 @@ describe('InstrumentRepoSyncLogTable', () => { cells.forEach((cell) => expect(cell.className).toContain('whitespace-nowrap')); }); + it('should name how many of the imported instruments were new, so the total is not read as all new', () => { + render(
); + expect(within(rows()[0]!).getByText('22 (12 new)')).toBeTruthy(); + }); + + it('should spell the whole split out on hover, since the cell has room for only the total', () => { + render(
); + expect(within(rows()[0]!).getByText('22 (12 new)').title).toBe('22 imported: 12 new, 10 already stored'); + }); + + it('should show the total alone for an entry that imported nothing, which stored nothing to split', () => { + render( +
+ ); + const cell = within(rows()[0]!).getByText('0'); + expect(cell.title).toBe('0'); + }); + + it('should show the total alone for an entry recorded before the split was counted', () => { + render(
); + const cell = within(rows()[0]!).getByText('22'); + expect(cell.title).toBe('22'); + }); + it('should carry the full repository name as a hover title, since the cell may clip it', () => { const repoName = 'LaboratoireDeRecherche/instruments-cliniques-internes'; render(
); diff --git a/apps/web/src/routes/_app/admin/instrument-repos/__tests__/index.test.tsx b/apps/web/src/routes/_app/admin/instrument-repos/__tests__/index.test.tsx index 030e6b0fb..bb132e4c0 100644 --- a/apps/web/src/routes/_app/admin/instrument-repos/__tests__/index.test.tsx +++ b/apps/web/src/routes/_app/admin/instrument-repos/__tests__/index.test.tsx @@ -549,18 +549,36 @@ describe('Route', () => { expect(screen.getByText('No instruments found in this repository.')).toBeTruthy(); }); - it('should list only the instruments that came from the viewed repository', () => { + it('should list only the instruments the viewed repository provides', () => { mocks.instrumentInfo.data = [ scalarFixture({ id: 'form-1', title: 'Happiness Questionnaire' }), - scalarFixture({ id: 'form-2', sourceRepo: { id: 'repo-2', name: 'Other Repo' }, title: 'Breakfast Survey' }), - scalarFixture({ id: 'form-3', sourceRepo: null, title: 'Manual Upload' }) + scalarFixture({ id: 'form-2', title: 'Breakfast Survey' }), + scalarFixture({ id: 'form-3', title: 'Elsewhere Survey' }) ]; - renderPage(); + renderPage([repoFixture({ instrumentIds: ['form-1', 'form-2'] })]); fireEvent.click(rowAction('View')); const dialog = within(screen.getByRole('dialog')); expect(dialog.getByText('Happiness Questionnaire')).toBeTruthy(); - expect(dialog.queryByText('Breakfast Survey')).toBeNull(); - expect(dialog.queryByText('Manual Upload')).toBeNull(); + expect(dialog.getByText('Breakfast Survey')).toBeTruthy(); + expect(dialog.queryByText('Elsewhere Survey')).toBeNull(); + }); + + // The import counts an instrument it found already stored, but leaves its provenance alone, so + // listing by provenance dropped exactly these while the activity log still counted them. + it('should list an instrument the repository provides but did not create, which provenance omits', () => { + mocks.instrumentInfo.data = [ + scalarFixture({ id: 'form-1', sourceRepo: null, title: 'Uploaded Before The Repo' }), + scalarFixture({ + id: 'form-2', + sourceRepo: { id: 'repo-2', name: 'Other Repo' }, + title: 'Shared With Another Repo' + }) + ]; + renderPage([repoFixture({ instrumentIds: ['form-1', 'form-2'] })]); + fireEvent.click(rowAction('View')); + const dialog = within(screen.getByRole('dialog')); + expect(dialog.getByText('Uploaded Before The Repo')).toBeTruthy(); + expect(dialog.getByText('Shared With Another Repo')).toBeTruthy(); }); it('should show the edition of a scalar instrument and a dash for a series, which has none', () => { @@ -568,7 +586,7 @@ describe('Route', () => { scalarFixture({ edition: 3, id: 'form-1', title: 'Happiness Questionnaire' }), seriesFixture({ id: 'series-1', title: 'Baseline Battery' }) ]; - renderPage(); + renderPage([repoFixture({ instrumentIds: ['form-1', 'series-1'] })]); fireEvent.click(rowAction('View')); const editions = within(screen.getByRole('dialog')) .getAllByRole('listitem') @@ -576,26 +594,14 @@ describe('Route', () => { expect(editions).toEqual(['3', '-']); }); - it('should list only the latest edition of an instrument the repository has bumped', () => { + // A bumped form is a new edition with an id of its own, and the sync replaces the id list, so the + // superseded edition stays in the database without being something the repository still provides. + it('should list only the edition of a bumped instrument that the repository still provides', () => { mocks.instrumentInfo.data = [ scalarFixture({ edition: 4, id: 'form-1', internalName: 'GI', title: 'General Information' }), scalarFixture({ edition: 5, id: 'form-2', internalName: 'GI', title: 'General Information' }) ]; - renderPage(); - fireEvent.click(rowAction('View')); - const editions = within(screen.getByRole('dialog')) - .getAllByRole('listitem') - .map((item) => item.querySelectorAll('p')[2]!.textContent); - expect(editions).toEqual(['5']); - }); - - // The API orders by nothing this page controls, so the newest edition may arrive first. - it('should keep the latest edition even when it comes before the superseded one in the data', () => { - mocks.instrumentInfo.data = [ - scalarFixture({ edition: 5, id: 'form-2', internalName: 'GI', title: 'General Information' }), - scalarFixture({ edition: 4, id: 'form-1', internalName: 'GI', title: 'General Information' }) - ]; - renderPage(); + renderPage([repoFixture({ instrumentIds: ['form-2'] })]); fireEvent.click(rowAction('View')); const editions = within(screen.getByRole('dialog')) .getAllByRole('listitem') @@ -603,14 +609,30 @@ describe('Route', () => { expect(editions).toEqual(['5']); }); - it('should count only the latest edition of each instrument once the instrument info has loaded', () => { + it('should count every instrument the repository provides, matching what the activity log imported', () => { mocks.instrumentInfo.data = [ scalarFixture({ edition: 4, id: 'form-1', internalName: 'GI', title: 'General Information' }), scalarFixture({ edition: 5, id: 'form-2', internalName: 'GI', title: 'General Information' }), seriesFixture({ id: 'series-1', title: 'Baseline Battery' }) ]; renderPage([repoFixture({ instrumentIds: ['form-1', 'form-2', 'series-1'] })]); - expect(within(rows()[0]!).getByText('2')).toBeTruthy(); + expect(within(rows()[0]!).getByText('3')).toBeTruthy(); + }); + + // Nothing prunes the id list when an instrument is deleted, so the count has to resolve the same ids + // the dialog lists, or the row would claim one the dialog cannot show. + it('should leave an id whose instrument was deleted out of the count, as the dialog leaves it out', () => { + mocks.instrumentInfo.data = [scalarFixture({ id: 'form-1', title: 'Happiness Questionnaire' })]; + renderPage([repoFixture({ instrumentIds: ['form-1', 'deleted-form'] })]); + expect(within(rows()[0]!).getByText('1')).toBeTruthy(); + fireEvent.click(rowAction('View')); + expect(within(screen.getByRole('dialog')).getAllByRole('listitem')).toHaveLength(1); + }); + + it('should count what the repository provides before the instrument info has loaded, since it needs none', () => { + renderPage([repoFixture({ instrumentIds: ['form-1', 'form-2', 'form-3'] })]); + expect(mocks.instrumentInfo.data).toBeUndefined(); + expect(within(rows()[0]!).getByText('3')).toBeTruthy(); }); it('should link to the repository source in the view dialog, so it can be opened on GitHub', () => { diff --git a/apps/web/src/routes/_app/admin/instrument-repos/index.tsx b/apps/web/src/routes/_app/admin/instrument-repos/index.tsx index 7f68f7b9e..0b8146a93 100644 --- a/apps/web/src/routes/_app/admin/instrument-repos/index.tsx +++ b/apps/web/src/routes/_app/admin/instrument-repos/index.tsx @@ -45,27 +45,17 @@ import { useSyncInstrumentRepoMutation } from '@/hooks/useSyncInstrumentRepoMuta import { MIN_TABLE_BODY_HEIGHT } from '@/utils/data-table'; /** - * The instruments a repository currently provides: only the latest edition of each. Superseded - * editions keep their repository provenance (records may still reference them), so without this a - * bumped form would be listed once per edition it has ever had. + * The instruments a repository provides, as its last sync recorded them — the same set the activity + * log counted as imported. + * + * Resolved through that id list rather than through each instrument's `sourceRepo`, which names + * whichever import created it. An instrument already stored when the repository was registered is + * provided by it but was not created by it, so listing by provenance silently drops every one of + * those while the log still counts them. */ -function currentRepoInstruments(instruments: TranslatedInstrumentInfo[], repoId: string) { - const fromRepo = instruments.filter((instrument) => instrument.sourceRepo?.id === repoId); - // Keyed by internal name, which is what identifies one instrument across its editions. A series - // has no edition of its own, so it is never superseded and never keyed. - const latestEditions = new Map(); - for (const instrument of fromRepo) { - if (instrument.kind === 'SERIES') { - continue; - } - const latest = latestEditions.get(instrument.internal.name); - if (latest === undefined || latest < instrument.internal.edition) { - latestEditions.set(instrument.internal.name, instrument.internal.edition); - } - } - return fromRepo.filter((instrument) => { - return instrument.kind === 'SERIES' || latestEditions.get(instrument.internal.name) === instrument.internal.edition; - }); +function providedInstruments(instruments: TranslatedInstrumentInfo[], repo: InstrumentRepo) { + const providedIds = new Set(repo.instrumentIds); + return instruments.filter((instrument) => providedIds.has(instrument.id)); } const AddRepoForm = ({ @@ -217,8 +207,8 @@ const RouteComponent = () => { }); const latestSyncLogsQuery = useLatestInstrumentRepoSyncLogsQuery(); const clearSyncLogsMutation = useClearInstrumentRepoSyncLogsMutation(); - // Every edition, because the default collapses editions across all sources, not per repository; - // `currentRepoInstruments` then keeps the latest edition each repository provides. + // Every edition, because a repository's id list names the exact editions it provides, and the + // default collapses editions across all sources — which would hide any a repository still provides. const instrumentInfoQuery = useInstrumentInfoQuery({ params: { allEditions: true } }); const [isDialogOpen, setIsDialogOpen] = useState(false); const [isConfirmDeleteOpen, setIsConfirmDeleteOpen] = useState(false); @@ -239,8 +229,11 @@ const RouteComponent = () => { const repoRows = reposQuery.data.map((repo) => ({ ...repo, failedCount: latestSyncLogByRepoId.get(repo.id)?.failures.length, + // The same function the View dialog lists, so the count and the list cannot disagree: an id whose + // instrument has since been deleted is in neither. Until the instruments load there is nothing to + // resolve the ids against, and the length of the list itself is the better of the two answers. instrumentCount: instrumentInfoQuery.data - ? currentRepoInstruments(instrumentInfoQuery.data, repo.id).length + ? providedInstruments(instrumentInfoQuery.data, repo).length : repo.instrumentIds.length })); @@ -368,6 +361,9 @@ const RouteComponent = () => { }, { accessorKey: 'instrumentCount', + cell: (ctx) => ( + {ctx.row.original.instrumentCount} + ), header: ({ column }) => ( { const searchTerm = instrumentSearch.trim().toLowerCase(); const repoInstruments = instrumentInfoQuery.data && - currentRepoInstruments(instrumentInfoQuery.data, repoToView.id).filter((instrument) => { + providedInstruments(instrumentInfoQuery.data, repoToView).filter((instrument) => { return instrument.details.title.toLowerCase().includes(searchTerm); }); if (instrumentInfoQuery.isLoading) { diff --git a/apps/web/src/utils/instrument-repo-sync.ts b/apps/web/src/utils/instrument-repo-sync.ts index 740007be1..fea8bec7e 100644 --- a/apps/web/src/utils/instrument-repo-sync.ts +++ b/apps/web/src/utils/instrument-repo-sync.ts @@ -2,12 +2,20 @@ import type { InstrumentRepoSyncLog } from '@opendatacapture/schemas/instrument- type InstrumentRepoSyncStatus = 'FAILED' | 'PARTIAL' | 'SUCCESS'; -/** A sync that could not read the repository failed outright; one that skipped instruments partly succeeded. */ +/** + * A sync that could not read the repository failed outright; one that stored some of its instruments + * and skipped others partly succeeded. Skipping every instrument is not a partial success: the + * repository was readable, but nothing was imported, so there is no success for the failures to be + * part of. + */ function getSyncStatus(log: InstrumentRepoSyncLog): InstrumentRepoSyncStatus { if (log.message) { return 'FAILED'; } - return log.failures.length ? 'PARTIAL' : 'SUCCESS'; + if (!log.failures.length) { + return 'SUCCESS'; + } + return log.importedCount > 0 ? 'PARTIAL' : 'FAILED'; } export { getSyncStatus, type InstrumentRepoSyncStatus }; diff --git a/packages/schemas/src/instrument-repo/__tests__/instrument-repo.test.ts b/packages/schemas/src/instrument-repo/__tests__/instrument-repo.test.ts index e6567807e..699770724 100644 --- a/packages/schemas/src/instrument-repo/__tests__/instrument-repo.test.ts +++ b/packages/schemas/src/instrument-repo/__tests__/instrument-repo.test.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from 'vitest'; -import { $CreateInstrumentRepoData, $InstrumentRepo } from '../instrument-repo.js'; +import { $CreateInstrumentRepoData, $InstrumentRepo, $InstrumentRepoSyncLog } from '../instrument-repo.js'; describe('$InstrumentRepo', () => { it('should accept a repo with lastSyncedAt omitted, since it is nullish', () => { @@ -60,3 +60,24 @@ describe('$CreateInstrumentRepoData', () => { ).toBe(true); }); }); + +describe('$InstrumentRepoSyncLog', () => { + const log = { + action: 'SYNC', + createdAt: '2024-01-01T00:00:00.000Z', + failures: [], + importedCount: 22, + repoName: 'my-repo', + updatedAt: '2024-01-01T00:00:00.000Z' + }; + + it('should accept an entry with createdCount omitted, since entries recorded before it was counted have none', () => { + expect($InstrumentRepoSyncLog.safeParse({ ...log, id: 'log-1' }).success).toBe(true); + }); + it('should accept an entry whose createdCount is a subset of what it imported', () => { + expect($InstrumentRepoSyncLog.safeParse({ ...log, createdCount: 12, id: 'log-1' }).success).toBe(true); + }); + it('should reject a negative createdCount, which no count of created instruments can be', () => { + expect($InstrumentRepoSyncLog.safeParse({ ...log, createdCount: -1, id: 'log-1' }).success).toBe(false); + }); +}); diff --git a/packages/schemas/src/instrument-repo/instrument-repo.ts b/packages/schemas/src/instrument-repo/instrument-repo.ts index 388afaea0..c29c013e5 100644 --- a/packages/schemas/src/instrument-repo/instrument-repo.ts +++ b/packages/schemas/src/instrument-repo/instrument-repo.ts @@ -42,7 +42,13 @@ export const $InstrumentRepoSyncFailure = z.object({ export type InstrumentRepoSyncLog = z.infer; export const $InstrumentRepoSyncLog = $BaseModel.extend({ action: $InstrumentRepoSyncAction, + /** + * How many of `importedCount` this run stored for the first time; the rest were already in the + * database. Null on an entry recorded before the two were counted separately. + */ + createdCount: z.number().int().nonnegative().nullish(), failures: z.array($InstrumentRepoSyncFailure), + /** Every instrument the repository provided, whether this run created it or found it already stored. */ importedCount: z.number().int().nonnegative(), /** Set when the repository as a whole could not be read, in which case nothing was imported. */ message: z.string().nullish(), @@ -61,6 +67,7 @@ export type InstrumentRepoSyncLogsSortBy = z.infer { }); }); +test.describe('admin instrument repos empty repository', () => { + test.use({ actingRole: 'ADMIN' }); + + test('should name the directories it looked in when a repository provides no instruments', async ({ + getPageModel, + page + }) => { + const message = + 'Found no instruments in example/empty. An instrument is a directory holding an index.ts, index.tsx, index.js or index.jsx file, within lib/file, lib/forms, lib/interactive, lib/series at the root of the repository.'; + await page.route('**/v1/instrument-repos', (route) => { + if (route.request().method() !== 'POST') { + return route.continue(); + } + return route.fulfill({ json: { error: 'Bad Gateway', message, statusCode: 502 }, status: 502 }); + }); + const reposPage = await getPageModel('/admin/instrument-repos'); + + await reposPage.addRepositoryButton.click(); + await reposPage.githubUrlInput.fill('https://github.com/example/empty'); + await reposPage.importButton.click(); + + await expect(reposPage.$ref.getByText(message)).toBeVisible(); + await expect(reposPage.$ref.getByTestId('error-page')).toBeHidden(); + }); +}); + test.describe('admin instrument repos activity log', () => { test.use({ actingRole: 'ADMIN' }); @@ -106,6 +132,7 @@ test.describe('admin instrument repos activity log', () => { const partialSync = { action: 'SYNC', createdAt: '2026-10-28T00:00:00.000Z', + createdCount: 1, failures: [ { instrumentDir: 'CPP_SERIES', @@ -150,6 +177,29 @@ test.describe('admin instrument repos activity log', () => { expect(overflow.spill).toBeLessThanOrEqual(0); }); + // The count used to be read from each instrument's provenance, which names the import that created + // it, so an instrument the repository provides but did not create went uncounted here while the + // activity log still counted it as imported. + test('should count the instruments a repository provides, whichever import created them', async ({ + getPageModel, + page + }) => { + await page.route(/\/v1\/instruments\/info/, (route) => route.fulfill({ json: [] })); + const reposPage = await getPageModel('/admin/instrument-repos'); + + await expect(reposPage.dataTable.getByTestId('instrument-repo-instrument-count')).toHaveText('2'); + }); + + test('should say how many of the imported instruments were new, so the total is not read as all new', async ({ + getPageModel + }) => { + const reposPage = await getPageModel('/admin/instrument-repos'); + + await reposPage.openActivityLog(); + + await expect(reposPage.syncLogTable.getByText('2 (1 new)')).toBeVisible(); + }); + test('should count the failed instruments and explain them in the activity log', async ({ getPageModel }) => { const reposPage = await getPageModel('/admin/instrument-repos');