Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
ci(sdk): compare field names of loosely typed excluded pairs
Yudhi Armyndharisdc8d6bde8406
diff --git a/scripts/check-contract-shapes.mjs b/scripts/check-contract-shapes.mjsindex 4acc088d8..9c387eff7 100644--- a/scripts/check-contract-shapes.mjs+++ b/scripts/check-contract-shapes.mjs@@ -44,6 +44,14 @@* the goal is to shrink it to zero (usually by tightening the hand type; where the CONTRACT* under-describes reality, fix the backend DTO decorator, regenerate, and un-exclude).*+ * An excluded pair listed in NAMES_ONLY is still compared by field NAME in both directions (not by+ * optionality or token), so a renamed or dropped field in it fails the run. Those are the Go and Java+ * response types whose field TYPES are deliberately looser than the contract: a plain string where the+ * contract lists a vocabulary keeps a value the server adds later decodable and callers' string+ * handling compiling, and a defined type or a changed pointer would be a source break for a+ * published client. Only a pair whose every other field conforms belongs there; one that cannot be+ * read as wire fields at all (a hand-written MarshalJSON, a client-side flag) stays whole-excluded.+ ** A mapping only gates the types somebody remembered to list, so a new DTO used to ship ungated by* default. The coverage check closes that: every schema an exposed operation sends or returns* (request bodies and 2xx responses, nested schemas included, the resources sdk/README.md declares@@ -266,6 +274,15 @@ const EXCLUDED = {},};+/**+ * Excluded pairs that are still compared by field name (see the header). Each entry must also be in+ * EXCLUDED: the run fails on one that is not, so a retyped pair cannot keep the weaker comparison.+ */+const NAMES_ONLY = {+ 'sdk/go': ['ContactRecord', 'GroupPictureResponse', 'GroupSettings', 'StatusRecord', 'AuthValidateResponse'],+ 'sdk/java': ['GroupSettings', 'StatusRecord', 'AuthValidateResponse'],+};+const ACK_SHAPE ='every client answers it as the shared SuccessResult {success, message?}, which spans the success-only and the success-plus-message acks, so no single schema fits it';const INVITE_CODE_SHAPE =@@ -908,8 +925,17 @@ function isSimpleToken(token) {/*** Compares one hand type against one schema. Returns an array of human-readable diff lines —* empty when the pair conforms. Exported for the spec; the CLI loop below is a thin driver.+ * `namesOnly` keeps the field-name comparison and drops optionality and token (see NAMES_ONLY).*/-export function comparePair(handName, handMembers, schemaName, schema, schemas, compareOptionality = true) {+export function comparePair(+ handName,+ handMembers,+ schemaName,+ schema,+ schemas,+ compareOptionality = true,+ namesOnly = false,+) {const diffs = [];const schemaFields = parseObjectToken(schemaToken(schema, schemas));for (const [field, handInfo] of Object.entries(handMembers)) {@@ -918,6 +944,7 @@ export function comparePair(handName, handMembers, schemaName, schema, schemas,diffs.push(`hand has "${field}" — contract does not`);continue;}+ if (namesOnly) continue;if (compareOptionality && handInfo.optional !== sField.optional) {diffs.push(`"${field}": hand ${handInfo.optional ? 'optional' : 'required'}, contract ${sField.optional ? 'optional' : 'required'}`,@@ -1468,6 +1495,7 @@ if (isDirectRun) {load: () => parseHandTypes(readFileSync(`${REPO_ROOT}${file}`, 'utf8')),mapping,excluded: EXCLUDED[file] ?? {},+ namesOnly: NAMES_ONLY[file] ?? [],floor: MINIMUM_MAPPED[file],compareOptionality: true,sdk: file.startsWith('sdk/'),@@ -1477,6 +1505,7 @@ if (isDirectRun) {load: () => parsePythonTypes(readFileSync(`${REPO_ROOT}sdk/python/openwa/types.py`, 'utf8')),mapping: PYTHON_MAPPING,excluded: EXCLUDED['sdk/python/openwa/types.py'] ?? {},+ namesOnly: NAMES_ONLY['sdk/python/openwa/types.py'] ?? [],floor: MINIMUM_MAPPED['sdk/python/openwa/types.py'],compareOptionality: true,sdk: true,@@ -1486,6 +1515,7 @@ if (isDirectRun) {load: () => parseGoTypes(goSources()),mapping: GO_MAPPING,excluded: EXCLUDED['sdk/go'] ?? {},+ namesOnly: NAMES_ONLY['sdk/go'] ?? [],floor: MINIMUM_MAPPED['sdk/go'],compareOptionality: true,sdk: true,@@ -1495,6 +1525,7 @@ if (isDirectRun) {load: () => parseJavaTypes(javaSources()),mapping: JAVA_MAPPING,excluded: EXCLUDED['sdk/java'] ?? {},+ namesOnly: NAMES_ONLY['sdk/java'] ?? [],floor: MINIMUM_MAPPED['sdk/java'],compareOptionality: false,sdk: true,@@ -1509,8 +1540,16 @@ if (isDirectRun) {let fileCompared = 0;const fileResults = [];+ for (const name of client.namesOnly.filter(n => !client.excluded[n])) {+ fileResults.push(+ ` ${name} is in NAMES_ONLY but not in EXCLUDED: remove it, or the pair is compared by name only`,+ );+ failures++;+ }+for (const [handName, target] of Object.entries(client.mapping)) {- if (client.excluded[handName]) continue;+ const namesOnly = Boolean(client.excluded[handName]) && client.namesOnly.includes(handName);+ if (client.excluded[handName] && !namesOnly) continue;const hand = handTypes[handName];if (!hand) {fileResults.push(` MISSING hand type ${handName} (declared in mapping but not found in ${client.label})`);@@ -1528,7 +1567,7 @@ if (isDirectRun) {}fileCompared++;compared++;- const diffs = comparePair(handName, hand, schemaName, schema, schemas, client.compareOptionality);+ const diffs = comparePair(handName, hand, schemaName, schema, schemas, client.compareOptionality, namesOnly);if (diffs.length) {fileResults.push(` ${handName} ↔ ${schemaName}:`, ...diffs.map(d => ` ${d}`));failures++;@@ -1550,7 +1589,8 @@ if (isDirectRun) {for (const line of fileResults) console.log(line);const excludedCount = Object.keys(client.excluded).length;if (excludedCount) {- console.log(` (${excludedCount} excluded pair(s) with recorded reasons — see EXCLUDED in this script)`);+ const byName = client.namesOnly.length ? `, ${client.namesOnly.length} of them still compared by field name` : '';+ console.log(` (${excludedCount} excluded pair(s) with recorded reasons, see EXCLUDED in this script${byName})`);}}diff --git a/scripts/check-contract-shapes.spec.mjs b/scripts/check-contract-shapes.spec.mjsindex 97c2999f0..fc391ca3a 100644--- a/scripts/check-contract-shapes.spec.mjs+++ b/scripts/check-contract-shapes.spec.mjs@@ -129,6 +129,23 @@ test('comparePair flags a primitive widened to a union of primitives', () => {assert.ok(diffs.some(d => d.includes('"count": hand union(int,str), contract number')));});+test('comparePair with namesOnly keeps the field names and drops optionality and token', () => {+ // The excluded Go and Java pairs keep a deliberately looser type: that stays accepted, a renamed field does not.+ const loose = {+ id: { optional: true, token: 'number' },+ direction: { optional: false, token: 'string' },+ count: { optional: false, token: 'string' },+ name: { optional: false, token: 'string' },+ };+ assert.deepEqual(comparePair('Sample', loose, 'SampleDto', schemas.SampleDto, schemas, true, true), []);+ assert.ok(comparePair('Sample', loose, 'SampleDto', schemas.SampleDto, schemas, true).length > 0);+ const renamed = { ...loose, nmae: loose.name };+ delete renamed.name;+ const diffs = comparePair('Sample', renamed, 'SampleDto', schemas.SampleDto, schemas, true, true);+ assert.equal(diffs.length, 2);+ assert.ok(diffs[0].startsWith('hand has "nmae"') && diffs[1].startsWith('contract has "name"'));+});+test('parseObjectToken splits nested object tokens without losing members', () => {const members = parseObjectToken('object(id:string,sub:object(a:number,b?:boolean),tail:string)');assert.deepEqual(Object.keys(members), ['id', 'sub', 'tail']);@@ -526,8 +543,16 @@ const gateRoot = fileURLToPath(new URL('..', import.meta.url));* sources linked in. A hook receives the original text (the parsed contract for `contract`) and returns the* one to use. Every file is read with LF endings, so a hook anchors the same text on any checkout, and* written with `lineEnding`: '\r\n' also copies the SDK sources the gate reads, as a Windows checkout has them.+ * `sdk` maps a path under the repository (`sdk/go/types_group.go`) to such a hook for one SDK source, which+ * also makes the run copy the SDK sources instead of linking them.*/-function runGateOnCopy({ script = s => s, contract = c => c, dashboardTypes = s => s, lineEnding = '\n' } = {}) {+function runGateOnCopy({+ script = s => s,+ contract = c => c,+ dashboardTypes = s => s,+ lineEnding = '\n',+ sdk = {},+} = {}) {const dir = mkdtempSync(join(tmpdir(), 'contract-shapes-copy-'));const read = (...path) => readFileSync(join(gateRoot, ...path), 'utf8').replace(/\r\n/g, '\n');const write = (path, text) => {@@ -535,7 +560,7 @@ function runGateOnCopy({ script = s => s, contract = c => c, dashboardTypes = swriteFileSync(join(dir, ...path), text.replace(/\n/g, lineEnding));};try {- if (lineEnding === '\n') {+ if (lineEnding === '\n' && !Object.keys(sdk).length) {symlinkSync(join(gateRoot, 'sdk'), join(dir, 'sdk'));} else {const modelDir = ['sdk', 'java', 'src', 'main', 'java', 'com', 'rmyndharis', 'openwa', 'model'];@@ -550,7 +575,13 @@ function runGateOnCopy({ script = s => s, contract = c => c, dashboardTypes = s.filter(f => f.endsWith('.java')).map(f => [...modelDir, f]),];- for (const path of sources) write(path, read(...path));+ for (const path of sources) write(path, (sdk[path.join('/')] ?? (text => text))(read(...path)));+ for (const path of Object.keys(sdk)) {+ assert.ok(+ sources.some(s => s.join('/') === path),+ `${path} is not an SDK source the gate reads`,+ );+ }}write(['scripts', 'check-contract-shapes.mjs'], script(read('scripts', 'check-contract-shapes.mjs')));write(@@ -636,6 +667,82 @@ test('a schema that only the dashboard compares, or only an excluded pair holds,);});+const javaModel = 'sdk/java/src/main/java/com/rmyndharis/openwa/model';++test('an excluded pair with a looser field type is still compared by field name', () => {+ // Each pair keeps a plain string (or a pointer) where the contract is stricter, so it is excluded from the+ // full comparison. Renaming one wire field in the hand type must still fail the run, naming the pair.+ const rename = (from, to) => text => editSource(text, from, to);+ const cases = [+ ['sdk/go/types_contact.go', 'ContactRecord ↔ ContactDto', 'json:"isBlocked"', 'json:"isBlockedd"', 'isBlockedd'],+ [+ 'sdk/go/types_group.go',+ 'GroupPictureResponse ↔ GroupPictureResponseDto',+ 'URL string `json:"url"`',+ 'URL string `json:"uri"`',+ 'uri',+ ],+ [+ 'sdk/go/types_group.go',+ 'GroupSettings ↔ GroupSettingsResponseDto',+ 'MemberAddMode *string `json:"memberAddMode,omitempty"`',+ 'MemberAddMode *string `json:"memberAddmode,omitempty"`',+ 'memberAddmode',+ ],+ [+ 'sdk/go/types_status.go',+ 'StatusRecord ↔ StatusDto',+ 'json:"backgroundColor,omitempty"',+ 'json:"backgroundColour,omitempty"',+ 'backgroundColour',+ ],+ [+ 'sdk/go/types_misc.go',+ 'AuthValidateResponse ↔ ValidateApiKeyResponseDto',+ 'json:"engineType,omitempty"',+ 'json:"engine,omitempty"',+ 'engine',+ ],+ [+ `${javaModel}/GroupSettings.java`,+ 'GroupSettings ↔ GroupSettingsResponseDto',+ 'String memberAddMode) {',+ 'String memberAddModes) {',+ 'memberAddModes',+ ],+ [+ `${javaModel}/StatusRecord.java`,+ 'StatusRecord ↔ StatusDto',+ ' String backgroundColor,',+ ' String backgroundColour,',+ 'backgroundColour',+ ],+ [+ `${javaModel}/AuthValidateResponse.java`,+ 'AuthValidateResponse ↔ ValidateApiKeyResponseDto',+ 'String engineType,',+ 'String engine,',+ 'engine',+ ],+ ];+ for (const [path, pair, from, to, renamed] of cases) {+ const run = runGateOnCopy({ sdk: { [path]: rename(from, to) } });+ assert.equal(run.status, 1, `${path}: ${run.output}`);+ assert.ok(run.output.includes(`${pair}:`), `${path} did not fail on ${pair}: ${run.output}`);+ assert.match(run.output, new RegExp(`hand has "${renamed}"`), path);+ }+});++test('the gate refuses a NAMES_ONLY entry whose pair is not excluded', () => {+ // An entry left behind after a pair is retyped and un-excluded would keep the weaker name-only comparison.+ const run = runGateOnCopy({+ script: source =>+ editSource(source, " 'sdk/java': ['GroupSettings',", " 'sdk/java': ['ContactRecord', 'GroupSettings',"),+ });+ assert.equal(run.status, 1, run.output);+ assert.match(run.output, /ContactRecord is in NAMES_ONLY but not in EXCLUDED/);+});+test('the gate and its CLI cases give the same verdicts on a CRLF checkout', () => {// A Windows checkout holds every file with CRLF endings: the parsers, the README reading and the anchors of// these cases must not depend on them. The existing case above covers the parsers on strings only.