diff --git a/locales/en/audits.json b/locales/en/audits.json index 90bf2dddf..dbf5601b7 100644 --- a/locales/en/audits.json +++ b/locales/en/audits.json @@ -13,7 +13,7 @@ "HH_M_Size": "Household size is missing", "HH_M_CarNumber": "Car number is missing", "HH_I_CarNumber": "Car number is out of range (should be an integer between 0 and 13)", - "HH_L_CarNumberPerPotentialDrivingLicenseTooHigh": "Car number per potential driving license holder > 3", + "HH_W_CarNumberPerPotentialDrivingLicenseTooHigh": "Car number per potential driving license holder > 3", "HH_L_SizeMembersCountMismatch": "Size and members count mismatch", "HH_L_InvalidPersonSequences": "At least one person sequence is invalid or duplicated", "HH_W_PersonSequenceGaps": "Person sequences are not contiguous", @@ -23,7 +23,7 @@ "HH_M_AtLeastOnePersonWithDisability": "At least one person with disability is missing", "HM_I_preGeographyAndHomeGeographyTooFarApartError": "Pre-filled and declared home geographies are far apart", - "HM_I_preGeographyAndHomeGeographyTooFarApartWarning": "Pre-filled and declared home geographies are a bit far apart", + "HM_W_preGeographyAndHomeGeographyTooFarApart": "Pre-filled and declared home geographies are a bit far apart", "HM_M_Geography": "Home geography is missing", "HM_I_Geography": "Home geography is invalid", "HM_I_geographyNotInSurveyTerritory": "Home geography is outside the survey territory", diff --git a/locales/fr/audits.json b/locales/fr/audits.json index 4877ff7a2..20867620a 100644 --- a/locales/fr/audits.json +++ b/locales/fr/audits.json @@ -13,7 +13,7 @@ "HH_M_Size": "La taille du ménage est manquante", "HH_M_CarNumber": "Le nombre de véhicules automobiles est manquant", "HH_I_CarNumber": "Le nombre de véhicules automobiles est en dehors de la plage autorisée (devrait être un entier entre 0 et 13)", - "HH_L_CarNumberPerPotentialDrivingLicenseTooHigh": "Le nombre de véhicules automobiles par titulaire potentiel d'un permis de conduire > 3", + "HH_W_CarNumberPerPotentialDrivingLicenseTooHigh": "Le nombre de véhicules automobiles par titulaire potentiel d'un permis de conduire > 3", "HH_L_SizeMembersCountMismatch": "La taille du ménage et le nombre de personnes ne correspondent pas", "HH_L_InvalidPersonSequences": "Le numéro de séquence d'au moins une personne est invalide ou en double", "HH_W_PersonSequenceGaps": "Les numéros de séquence des personnes ne sont pas consécutifs", @@ -23,7 +23,7 @@ "HH_M_AtLeastOnePersonWithDisability": "La présence d'au moins une personne avec un handicap est manquante", "HM_I_preGeographyAndHomeGeographyTooFarApartError": "Les géographies pré-remplie et déclarée du domicile sont éloignées", - "HM_I_preGeographyAndHomeGeographyTooFarApartWarning": "Les géographies pré-remplie et déclarée du domicile sont un peu éloignées", + "HM_W_preGeographyAndHomeGeographyTooFarApart": "Les géographies pré-remplie et déclarée du domicile sont un peu éloignées", "HM_M_Geography": "La géographie du domicile est manquante", "HM_I_Geography": "La géographie du domicile est invalide", "HM_I_geographyNotInSurveyTerritory": "La géographie du domicile est en dehors du territoire d'enquête", diff --git a/packages/evolution-backend/src/services/audits/auditChecks/README.md b/packages/evolution-backend/src/services/audits/auditChecks/README.md index 73b1aa36e..bf120f5db 100644 --- a/packages/evolution-backend/src/services/audits/auditChecks/README.md +++ b/packages/evolution-backend/src/services/audits/auditChecks/README.md @@ -106,22 +106,29 @@ All contexts are defined in [`./AuditCheckContexts.ts`](./AuditCheckContexts.ts) ### 3.2 What kind of problem is it? +> **TODO:** The prefixes below mix audit *type* (missing, invalid, logical) with *severity* (info, warning). This is historical (`M`/`I`/`L` from 2023; `W` and `F` were added later). A cleaner split is tracked in [#1771](https://github.com/chairemobilite/evolution/issues/1771). + Follow the existing prefix convention (see the checks folder README): - `_M_` — **Missing** required data (`HH_M_Size`). - `_I_` — **Invalid** data (`HH_I_Size` — out of range, malformed, wrong type). - `_L_` — **Logical** inconsistency between fields or objects (`HH_L_SizeMembersCountMismatch`). +- `_F_` — **Info** — informational flag, not an error or warning (`HH_F_AtLeastOneTransitSegmentInHousehold`). +- `_W_` — **Warning** — suspicious data that may be fine but needs reviewer attention (`HH_W_CarNumberPerPotentialDrivingLicenseTooHigh`, `HM_W_preGeographyAndHomeGeographyTooFarApart`). Pick `_M_` only if the field should always be present. If "required" depends on survey configuration, use `fieldIsRequired(...)` (see §5.1) and still prefix with `_M_`. +The type prefix should match the audit `level`: use `_W_` with `level: 'warning'`, `_F_` with `level: 'info'`, and `_M_` / `_I_` / `_L_` with `level: 'error'`. + ### 3.3 Which severity? +> **TODO:** Same conflation as §3.2 — this table maps severity to prefixes, but `error` still spans three type letters (`M`, `I`, `L`) instead of one. See [#1771](https://github.com/chairemobilite/evolution/issues/1771). -| Level | Meaning | Reviewer behavior expected | -| --------- | -------------------------------------------------------------------------- | -------------------------------------- | -| `error` | The data is wrong or unusable and must be corrected or explicitly ignored. | Must look at it. | -| `warning` | Something suspicious that often turns out fine. | Should look at it when they have time. | -| `info` | Informational only, typically for stats or routing. | Can ignore. | +| Level | Prefix | Meaning | Reviewer behavior expected | +| --------- | ------ | -------------------------------------------------------------------------- | -------------------------------------- | +| `error` | `M`, `I`, or `L` | The data is wrong or unusable and must be corrected or explicitly ignored. | Must look at it. | +| `warning` | `W` | Something suspicious that often turns out fine. | Should look at it when they have time. | +| `info` | `F` | Informational only, typically for stats or routing. | Can ignore. | When in doubt, start at `warning`. Escalating later is cheap; downgrading creates review backlog. @@ -293,7 +300,7 @@ Grep before adding to avoid duplicates. Checks live in `AuditChecks.ts` and `ExtendedAuditChecks.ts` under [`./checks/`](./checks/), one file per survey object type (see the table in §3.1). To list all current checks: ```bash -grep -rEn "^[[:space:]]+[IHMPJVTS]{1,2}_[MIL]_[A-Za-z]+:" \ +grep -rEn "^[[:space:]]+[IHMPJVTS]{1,2}_[MILFW]_[A-Za-z]+:" \ packages/evolution-backend/src/services/audits/auditChecks/checks ``` diff --git a/packages/evolution-backend/src/services/audits/auditChecks/checks/HomeAuditChecks.ts b/packages/evolution-backend/src/services/audits/auditChecks/checks/HomeAuditChecks.ts index a7d3225bf..06d84041a 100644 --- a/packages/evolution-backend/src/services/audits/auditChecks/checks/HomeAuditChecks.ts +++ b/packages/evolution-backend/src/services/audits/auditChecks/checks/HomeAuditChecks.ts @@ -108,9 +108,7 @@ export const homeAuditChecks: { [errorCode: string]: HomeAuditCheckFunction } = * @param context - HomeAuditCheckContext * @returns AuditForObject */ - HM_I_preGeographyAndHomeGeographyTooFarApartWarning: ( - context: HomeAuditCheckContext - ): AuditForObject | undefined => { + HM_W_preGeographyAndHomeGeographyTooFarApart: (context: HomeAuditCheckContext): AuditForObject | undefined => { const home = context.home; const preGeography = home.preGeography; const geography = home.geography; @@ -124,7 +122,7 @@ export const homeAuditChecks: { [errorCode: string]: HomeAuditCheckFunction } = return { objectType: 'home', objectUuid: home._uuid!, - errorCode: 'HM_I_preGeographyAndHomeGeographyTooFarApartWarning', + errorCode: 'HM_W_preGeographyAndHomeGeographyTooFarApart', version: 1, level: 'warning', message: 'Pre-filled and declared home geography are a bit far apart', diff --git a/packages/evolution-backend/src/services/audits/auditChecks/checks/HouseholdAuditChecks.ts b/packages/evolution-backend/src/services/audits/auditChecks/checks/HouseholdAuditChecks.ts index 793e91654..ffbe55f39 100644 --- a/packages/evolution-backend/src/services/audits/auditChecks/checks/HouseholdAuditChecks.ts +++ b/packages/evolution-backend/src/services/audits/auditChecks/checks/HouseholdAuditChecks.ts @@ -257,7 +257,7 @@ export const householdAuditChecks: { [errorCode: string]: HouseholdAuditCheckFun * @param context - HouseholdAuditCheckContext * @returns AuditForObject */ - HH_L_CarNumberPerPotentialDrivingLicenseTooHigh: ( + HH_W_CarNumberPerPotentialDrivingLicenseTooHigh: ( context: HouseholdAuditCheckContext ): AuditForObject | undefined => { const { household } = context; @@ -280,7 +280,7 @@ export const householdAuditChecks: { [errorCode: string]: HouseholdAuditCheckFun return { objectType: 'household', objectUuid: household._uuid!, - errorCode: 'HH_L_CarNumberPerPotentialDrivingLicenseTooHigh', + errorCode: 'HH_W_CarNumberPerPotentialDrivingLicenseTooHigh', version: 1, level: 'warning', message: 'Car number per potential driving license holder > 3', diff --git a/packages/evolution-backend/src/services/audits/auditChecks/checks/README.md b/packages/evolution-backend/src/services/audits/auditChecks/checks/README.md index b24182bbd..3c9a01292 100644 --- a/packages/evolution-backend/src/services/audits/auditChecks/checks/README.md +++ b/packages/evolution-backend/src/services/audits/auditChecks/checks/README.md @@ -22,7 +22,8 @@ All audit check functions follow the pattern: `[OBJECTPREFIX]_[AUDITCHECKTYPE]_[ - `M` - **Missing** data (e.g., `HH_M_Size` - household size is missing) - `I` - **Invalid** data (e.g., `HH_I_Size` - household size is out of valid range) - `L` - **Logical** error (e.g., `J_L_EndBeforeStart` - journey end time before start time) -- `W` - **Warning**: suspicious data that is still usable, worth a reviewer's attention (e.g., `HH_W_PersonSequenceGaps`). Use with `level: 'warning'`. +- `F` - **Info** — informational check, not an error or warning (e.g., `HH_F_AtLeastOneTransitSegmentInHousehold`). Use with `level: 'info'`. +- `W` - **Warning** — suspicious data that may indicate a possible error; needs review. Use with `level: 'warning'`. ### Examples ```typescript diff --git a/packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/home/HM_I_preGeographyAndHomeGeographyTooFarApartWarning.integration.test.ts b/packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/home/HM_W_preGeographyAndHomeGeographyTooFarApart.integration.test.ts similarity index 83% rename from packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/home/HM_I_preGeographyAndHomeGeographyTooFarApartWarning.integration.test.ts rename to packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/home/HM_W_preGeographyAndHomeGeographyTooFarApart.integration.test.ts index 8a04ea1ed..1670f6058 100644 --- a/packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/home/HM_I_preGeographyAndHomeGeographyTooFarApartWarning.integration.test.ts +++ b/packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/home/HM_W_preGeographyAndHomeGeographyTooFarApart.integration.test.ts @@ -9,7 +9,7 @@ import { v4 as uuidV4 } from 'uuid'; import { homeAuditChecks } from '../../HomeAuditChecks'; import { createContextWithHome } from './testHelper'; -describe('HM_I_preGeographyAndHomeGeographyTooFarApartWarning audit check - Integration tests with real turfDistance', () => { +describe('HM_W_preGeographyAndHomeGeographyTooFarApart audit check - Integration tests with real turfDistance', () => { const validUuid = uuidV4(); it('should warn when coordinates are moderately far apart (~93.5 meters)', () => { @@ -29,11 +29,11 @@ describe('HM_I_preGeographyAndHomeGeographyTooFarApartWarning audit check - Inte validUuid ); - const result = homeAuditChecks.HM_I_preGeographyAndHomeGeographyTooFarApartWarning(context); + const result = homeAuditChecks.HM_W_preGeographyAndHomeGeographyTooFarApart(context); expect(result).toBeDefined(); expect(result).toMatchObject({ - errorCode: 'HM_I_preGeographyAndHomeGeographyTooFarApartWarning', + errorCode: 'HM_W_preGeographyAndHomeGeographyTooFarApart', level: 'warning', objectType: 'home', objectUuid: validUuid @@ -57,7 +57,7 @@ describe('HM_I_preGeographyAndHomeGeographyTooFarApartWarning audit check - Inte validUuid ); - const result = homeAuditChecks.HM_I_preGeographyAndHomeGeographyTooFarApartWarning(context); + const result = homeAuditChecks.HM_W_preGeographyAndHomeGeographyTooFarApart(context); expect(result).toBeUndefined(); }); @@ -79,7 +79,7 @@ describe('HM_I_preGeographyAndHomeGeographyTooFarApartWarning audit check - Inte validUuid ); - const result = homeAuditChecks.HM_I_preGeographyAndHomeGeographyTooFarApartWarning(context); + const result = homeAuditChecks.HM_W_preGeographyAndHomeGeographyTooFarApart(context); expect(result).toBeUndefined(); }); diff --git a/packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/home/HM_I_preGeographyAndHomeGeographyTooFarApartWarning.test.ts b/packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/home/HM_W_preGeographyAndHomeGeographyTooFarApart.test.ts similarity index 90% rename from packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/home/HM_I_preGeographyAndHomeGeographyTooFarApartWarning.test.ts rename to packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/home/HM_W_preGeographyAndHomeGeographyTooFarApart.test.ts index b04685a74..3a47a2d83 100644 --- a/packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/home/HM_I_preGeographyAndHomeGeographyTooFarApartWarning.test.ts +++ b/packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/home/HM_W_preGeographyAndHomeGeographyTooFarApart.test.ts @@ -15,7 +15,7 @@ jest.mock('@turf/distance', () => ({ import { distance as turfDistance } from '@turf/distance'; -describe('HM_I_preGeographyAndHomeGeographyTooFarApartWarning audit check', () => { +describe('HM_W_preGeographyAndHomeGeographyTooFarApart audit check', () => { const validUuid = uuidV4(); beforeEach(() => { @@ -56,7 +56,7 @@ describe('HM_I_preGeographyAndHomeGeographyTooFarApartWarning audit check', () = validUuid ); - const result = homeAuditChecks.HM_I_preGeographyAndHomeGeographyTooFarApartWarning(context); + const result = homeAuditChecks.HM_W_preGeographyAndHomeGeographyTooFarApart(context); expect(result).toBeUndefined(); }); @@ -91,7 +91,7 @@ describe('HM_I_preGeographyAndHomeGeographyTooFarApartWarning audit check', () = validUuid ); - const result = homeAuditChecks.HM_I_preGeographyAndHomeGeographyTooFarApartWarning(context); + const result = homeAuditChecks.HM_W_preGeographyAndHomeGeographyTooFarApart(context); expect(result).toBeUndefined(); }); @@ -126,12 +126,12 @@ describe('HM_I_preGeographyAndHomeGeographyTooFarApartWarning audit check', () = validUuid ); - const result = homeAuditChecks.HM_I_preGeographyAndHomeGeographyTooFarApartWarning(context); + const result = homeAuditChecks.HM_W_preGeographyAndHomeGeographyTooFarApart(context); expect(result).toMatchObject({ objectType: 'home', objectUuid: validUuid, - errorCode: 'HM_I_preGeographyAndHomeGeographyTooFarApartWarning', + errorCode: 'HM_W_preGeographyAndHomeGeographyTooFarApart', level: 'warning', message: 'Pre-filled and declared home geography are a bit far apart', ignore: false diff --git a/packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/household/HH_L_CarNumberPerPotentialDrivingLicenseTooHigh.test.ts b/packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/household/HH_W_CarNumberPerPotentialDrivingLicenseTooHigh.test.ts similarity index 95% rename from packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/household/HH_L_CarNumberPerPotentialDrivingLicenseTooHigh.test.ts rename to packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/household/HH_W_CarNumberPerPotentialDrivingLicenseTooHigh.test.ts index 898694f94..4bc1922fd 100644 --- a/packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/household/HH_L_CarNumberPerPotentialDrivingLicenseTooHigh.test.ts +++ b/packages/evolution-backend/src/services/audits/auditChecks/checks/__tests__/household/HH_W_CarNumberPerPotentialDrivingLicenseTooHigh.test.ts @@ -12,7 +12,7 @@ import { householdAuditChecks, MAX_CAR_NUMBER_PER_POTENTIAL_DRIVING_LICENSE } fr import { createContextWithHouseholdAndHome } from './testHelper'; import { SurveyObjectsRegistry } from 'evolution-common/lib/services/baseObjects/SurveyObjectsRegistry'; -describe('HH_L_CarNumberPerPotentialDrivingLicenseTooHigh audit check', () => { +describe('HH_W_CarNumberPerPotentialDrivingLicenseTooHigh audit check', () => { const validHouseholdUuid = uuidV4(); const validHomeUuid = uuidV4(); const surveyObjectsRegistry = new SurveyObjectsRegistry(); @@ -74,13 +74,13 @@ describe('HH_L_CarNumberPerPotentialDrivingLicenseTooHigh audit check', () => { validHomeUuid ); - const result = householdAuditChecks.HH_L_CarNumberPerPotentialDrivingLicenseTooHigh(context); + const result = householdAuditChecks.HH_W_CarNumberPerPotentialDrivingLicenseTooHigh(context); if (shouldWarn) { expect(result).toMatchObject({ objectType: 'household', objectUuid: validHouseholdUuid, - errorCode: 'HH_L_CarNumberPerPotentialDrivingLicenseTooHigh', + errorCode: 'HH_W_CarNumberPerPotentialDrivingLicenseTooHigh', version: 1, level: 'warning', message: 'Car number per potential driving license holder > 3',