docusaurus-plugin-generate-schema-docs 1.7.1 → 1.8.1

package/__tests__/helpers/trackingTargets.test.js

@@ -0,0 +1,42 @@
+import {
+  DEFAULT_TRACKING_TARGET,
+  resolveTrackingTargets,
+} from '../../helpers/trackingTargets';
+
+describe('trackingTargets', () => {
+  it('returns the configured targets when valid', () => {
+    const schema = {
+      'x-tracking-targets': ['web-datalayer-js', 'android-firebase-java-sdk'],
+    };
+
+    const result = resolveTrackingTargets(schema, { schemaFile: 'event.json' });
+    expect(result).toEqual({
+      targets: ['web-datalayer-js', 'android-firebase-java-sdk'],
+      warning: null,
+      errors: [],
+    });
+  });
+
+  it('falls back to default target when key is missing', () => {
+    const result = resolveTrackingTargets(
+      {},
+      { schemaFile: 'event.json', isQuiet: false },
+    );
+
+    expect(result.targets).toEqual([DEFAULT_TRACKING_TARGET]);
+    expect(result.errors).toEqual([]);
+    expect(result.warning).toContain(DEFAULT_TRACKING_TARGET);
+  });
+
+  it('returns an error for unknown targets', () => {
+    const schema = {
+      'x-tracking-targets': ['web-not-supported-js'],
+    };
+
+    const result = resolveTrackingTargets(schema, { schemaFile: 'event.json' });
+
+    expect(result.targets).toEqual([]);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]).toContain('web-not-supported-js');
+  });
+});

package/__tests__/runtimePayload.android.test.js

@@ -0,0 +1,292 @@
+/* eslint jest/expect-expect: ["warn", { "assertFunctionNames": ["expect", "expectPayloadContract"] }] */
+const { generateSnippetForTarget } = require('../helpers/snippetTargets');
+const { PAYLOAD_CONTRACTS } = require('../test-data/payloadContracts');
+
+const ANDROID_CONTRACTS = PAYLOAD_CONTRACTS.filter(
+  (contract) => contract.expected?.firebase,
+);
+
+function upperSnakeToSnake(value) {
+  return value.toLowerCase();
+}
+
+function unquote(value) {
+  if (value.startsWith('"') && value.endsWith('"')) return JSON.parse(value);
+  return value;
+}
+
+function resolveAndroidEventToken(token) {
+  if (token.startsWith('"') && token.endsWith('"')) return JSON.parse(token);
+  const match = token.match(/^FirebaseAnalytics\.Event\.([A-Z0-9_]+)$/);
+  if (match) return upperSnakeToSnake(match[1]);
+  throw new Error(`Unsupported Android event token: ${token}`);
+}
+
+function resolveAndroidParamToken(token) {
+  if (token.startsWith('"') && token.endsWith('"')) return JSON.parse(token);
+  const match = token.match(/^FirebaseAnalytics\.Param\.([A-Z0-9_]+)$/);
+  if (match) return upperSnakeToSnake(match[1]);
+  throw new Error(`Unsupported Android parameter token: ${token}`);
+}
+
+function resolveAndroidUserPropertyToken(token) {
+  if (token.startsWith('"') && token.endsWith('"')) return JSON.parse(token);
+  const match = token.match(/^FirebaseAnalytics\.UserProperty\.([A-Z0-9_]+)$/);
+  if (!match)
+    throw new Error(`Unsupported Android user property token: ${token}`);
+  if (match[1] === 'ALLOW_AD_PERSONALIZATION_SIGNALS') {
+    return 'allow_personalized_ads';
+  }
+  return upperSnakeToSnake(match[1]);
+}
+
+function resolveAndroidValue(token) {
+  const value = token.trim();
+  if (value === 'null') return null;
+  if (value.startsWith('"') && value.endsWith('"')) return JSON.parse(value);
+  const longMatch = value.match(/^(-?\d+)L$/);
+  if (longMatch) return Number(longMatch[1]);
+  if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+  throw new Error(`Unsupported Android value token: ${value}`);
+}
+
+function splitArgs(content) {
+  let quote = null;
+  let escaped = false;
+  let roundDepth = 0;
+  let squareDepth = 0;
+  let curlyDepth = 0;
+
+  for (let idx = 0; idx < content.length; idx += 1) {
+    const char = content[idx];
+
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (char === '\\') {
+        escaped = true;
+        continue;
+      }
+      if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === '(') {
+      roundDepth += 1;
+      continue;
+    }
+    if (char === ')') {
+      roundDepth -= 1;
+      continue;
+    }
+    if (char === '[') {
+      squareDepth += 1;
+      continue;
+    }
+    if (char === ']') {
+      squareDepth -= 1;
+      continue;
+    }
+    if (char === '{') {
+      curlyDepth += 1;
+      continue;
+    }
+    if (char === '}') {
+      curlyDepth -= 1;
+      continue;
+    }
+    if (
+      char === ',' &&
+      roundDepth === 0 &&
+      squareDepth === 0 &&
+      curlyDepth === 0
+    ) {
+      return [content.slice(0, idx).trim(), content.slice(idx + 1).trim()];
+    }
+  }
+
+  throw new Error(`Unable to split function arguments: ${content}`);
+}
+
+function parseKotlinRuntimePayload(snippet) {
+  const lines = snippet.split('\n').map((line) => line.trim());
+  const itemBundles = {};
+  const userProperties = {};
+  const eventParams = {};
+  let eventName = null;
+  let inLogEvent = false;
+
+  for (let idx = 0; idx < lines.length; idx += 1) {
+    const line = lines[idx];
+    if (!line) continue;
+
+    const itemStart = line.match(/^val (item\d+) = Bundle\(\)\.apply \{$/);
+    if (itemStart) {
+      const itemName = itemStart[1];
+      itemBundles[itemName] = {};
+      idx += 1;
+      while (idx < lines.length && lines[idx] !== '}') {
+        const putLine = lines[idx];
+        const putMatch = putLine.match(/^put(?:String|Long|Double)\((.+)\)$/);
+        if (!putMatch)
+          throw new Error(`Unsupported Kotlin item line: ${putLine}`);
+        const [keyToken, valueToken] = splitArgs(putMatch[1]);
+        itemBundles[itemName][resolveAndroidParamToken(keyToken)] =
+          resolveAndroidValue(valueToken);
+        idx += 1;
+      }
+      continue;
+    }
+
+    const userMatch = line.match(
+      /^firebaseAnalytics\.setUserProperty\((.+)\)$/,
+    );
+    if (userMatch) {
+      const [keyToken, valueToken] = splitArgs(userMatch[1]);
+      const key = resolveAndroidUserPropertyToken(keyToken);
+      const value = resolveAndroidValue(valueToken);
+      userProperties[key] = value === null ? null : String(value);
+      continue;
+    }
+
+    const logStartMatch = line.match(
+      /^firebaseAnalytics\.logEvent\((.+)\) \{$/,
+    );
+    if (logStartMatch) {
+      eventName = resolveAndroidEventToken(logStartMatch[1].trim());
+      inLogEvent = true;
+      continue;
+    }
+
+    if (inLogEvent && line === '}') {
+      inLogEvent = false;
+      continue;
+    }
+
+    if (inLogEvent) {
+      const paramMatch = line.match(/^param\((.+)\)$/);
+      if (!paramMatch)
+        throw new Error(`Unsupported Kotlin param line: ${line}`);
+      const [keyToken, valueToken] = splitArgs(paramMatch[1]);
+      const key = resolveAndroidParamToken(keyToken);
+      const itemsMatch = valueToken.match(/^arrayOf\((.+)\)$/);
+      if (itemsMatch) {
+        const names = itemsMatch[1]
+          .split(',')
+          .map((name) => name.trim())
+          .filter(Boolean);
+        eventParams[key] = names.map((name) => itemBundles[name]);
+      } else {
+        eventParams[key] = resolveAndroidValue(valueToken);
+      }
+    }
+  }
+
+  return { eventName, parameters: eventParams, userProperties };
+}
+
+function parseJavaRuntimePayload(snippet) {
+  const lines = snippet.split('\n').map((line) => line.trim());
+  const bundles = {};
+  const userProperties = {};
+  let eventName = null;
+
+  for (let idx = 0; idx < lines.length; idx += 1) {
+    const line = lines[idx];
+    if (!line) continue;
+
+    const bundleStart = line.match(/^Bundle (\w+) = new Bundle\(\);$/);
+    if (bundleStart) {
+      bundles[bundleStart[1]] = {};
+      continue;
+    }
+
+    const putMatch = line.match(/^(\w+)\.put(?:String|Long|Double)\((.+)\);$/);
+    if (putMatch) {
+      const bundleName = putMatch[1];
+      const [keyToken, valueToken] = splitArgs(putMatch[2]);
+      bundles[bundleName][resolveAndroidParamToken(keyToken)] =
+        resolveAndroidValue(valueToken);
+      continue;
+    }
+
+    const parcelableMatch = line.match(
+      /^eventParams\.putParcelableArray\((.+), new Parcelable\[\]\{(.+)\}\);$/,
+    );
+    if (parcelableMatch) {
+      const key = resolveAndroidParamToken(parcelableMatch[1].trim());
+      const names = parcelableMatch[2]
+        .split(',')
+        .map((name) => name.trim())
+        .filter(Boolean);
+      bundles.eventParams[key] = names.map((name) => bundles[name]);
+      continue;
+    }
+
+    const userMatch = line.match(
+      /^mFirebaseAnalytics\.setUserProperty\((.+)\);$/,
+    );
+    if (userMatch) {
+      const [keyToken, valueToken] = splitArgs(userMatch[1]);
+      const key = resolveAndroidUserPropertyToken(keyToken);
+      const value = resolveAndroidValue(valueToken);
+      userProperties[key] = value === null ? null : String(value);
+      continue;
+    }
+
+    const logMatch = line.match(
+      /^mFirebaseAnalytics\.logEvent\((.+), eventParams\);$/,
+    );
+    if (logMatch) {
+      eventName = resolveAndroidEventToken(logMatch[1].trim());
+    }
+  }
+
+  return { eventName, parameters: bundles.eventParams || {}, userProperties };
+}
+
+function expectPayloadContract(parsed, expectedContract) {
+  expect(parsed.eventName).toBe(expectedContract.eventName);
+  expect(parsed.parameters || {}).toEqual(expectedContract.parameters || {});
+  expect(parsed.userProperties || {}).toEqual(
+    expectedContract.userProperties || {},
+  );
+}
+
+describe('runtime payload contracts (android)', () => {
+  it.each(ANDROID_CONTRACTS)(
+    'validates Kotlin runtime payload for $id ($class)',
+    (contract) => {
+      const snippet = generateSnippetForTarget({
+        targetId: 'android-firebase-kotlin-sdk',
+        example: contract.example,
+        schema: { properties: {} },
+      });
+
+      const parsed = parseKotlinRuntimePayload(snippet);
+      expectPayloadContract(parsed, contract.expected.firebase);
+    },
+  );
+
+  it.each(ANDROID_CONTRACTS)(
+    'validates Java runtime payload for $id ($class)',
+    (contract) => {
+      const snippet = generateSnippetForTarget({
+        targetId: 'android-firebase-java-sdk',
+        example: contract.example,
+        schema: { properties: {} },
+      });
+
+      const parsed = parseJavaRuntimePayload(snippet);
+      expectPayloadContract(parsed, contract.expected.firebase);
+    },
+  );
+});

package/__tests__/runtimePayload.ios.test.js

@@ -0,0 +1,282 @@
+/* eslint jest/expect-expect: ["warn", { "assertFunctionNames": ["expect", "expectPayloadContract"] }] */
+const { generateSnippetForTarget } = require('../helpers/snippetTargets');
+const { PAYLOAD_CONTRACTS } = require('../test-data/payloadContracts');
+const IOS_CONTRACTS = PAYLOAD_CONTRACTS.filter(
+  (contract) => contract.expected?.firebase,
+);
+
+function stripTrailingComma(value) {
+  return value.replace(/,+$/, '').trim();
+}
+
+function splitPair(line) {
+  const match = line.match(/^(.+?):\s*(.+)$/);
+  if (!match) {
+    throw new Error(`Cannot parse key/value line: ${line}`);
+  }
+  return {
+    keyToken: stripTrailingComma(match[1].trim()),
+    valueToken: stripTrailingComma(match[2].trim()),
+  };
+}
+
+function toSnakeCaseFromPascal(value) {
+  return value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+}
+
+function resolveEventToken(token) {
+  if (token.startsWith('"') && token.endsWith('"')) return JSON.parse(token);
+  if (token.startsWith('@"') && token.endsWith('"')) {
+    return JSON.parse(token.slice(1));
+  }
+  if (token.startsWith('AnalyticsEvent')) {
+    return toSnakeCaseFromPascal(token.slice('AnalyticsEvent'.length));
+  }
+  if (token.startsWith('kFIREvent')) {
+    return toSnakeCaseFromPascal(token.slice('kFIREvent'.length));
+  }
+  throw new Error(`Unsupported event token: ${token}`);
+}
+
+function resolveParamToken(token) {
+  if (token.startsWith('"') && token.endsWith('"')) return JSON.parse(token);
+  if (token.startsWith('@"') && token.endsWith('"')) {
+    return JSON.parse(token.slice(1));
+  }
+  if (token === 'AnalyticsParameterAdNetworkClickID') return 'aclid';
+  if (token === 'kFIRParameterAdNetworkClickID') return 'aclid';
+  if (token.startsWith('AnalyticsParameter')) {
+    return toSnakeCaseFromPascal(token.slice('AnalyticsParameter'.length));
+  }
+  if (token.startsWith('kFIRParameter')) {
+    return toSnakeCaseFromPascal(token.slice('kFIRParameter'.length));
+  }
+  throw new Error(`Unsupported parameter token: ${token}`);
+}
+
+function resolveUserPropertyToken(token) {
+  if (token.startsWith('"') && token.endsWith('"')) return JSON.parse(token);
+  if (token.startsWith('@"') && token.endsWith('"')) {
+    return JSON.parse(token.slice(1));
+  }
+  if (token === 'AnalyticsUserPropertySignUpMethod') return 'sign_up_method';
+  if (token === 'kFIRUserPropertySignUpMethod') return 'sign_up_method';
+  if (token === 'AnalyticsUserPropertyAllowAdPersonalizationSignals') {
+    return 'allow_personalized_ads';
+  }
+  if (token === 'kFIRUserPropertyAllowAdPersonalizationSignals') {
+    return 'allow_personalized_ads';
+  }
+  throw new Error(`Unsupported user property token: ${token}`);
+}
+
+function resolveSwiftValue(token) {
+  const value = token.trim();
+  if (value === 'nil') return null;
+  if (value.startsWith('"') && value.endsWith('"')) return JSON.parse(value);
+  if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
+  throw new Error(`Unsupported Swift value token: ${value}`);
+}
+
+function resolveObjcValue(token) {
+  const value = token.trim();
+  if (value === 'nil') return null;
+  if (value.startsWith('@"') && value.endsWith('"')) {
+    return JSON.parse(value.slice(1));
+  }
+  const numberMatch = value.match(/^@\((-?\d+(?:\.\d+)?)\)$/);
+  if (numberMatch) return Number(numberMatch[1]);
+  throw new Error(`Unsupported Obj-C value token: ${value}`);
+}
+
+function parseSwiftDictionary(lines, startIndex) {
+  const payload = {};
+  let idx = startIndex + 1;
+  while (idx < lines.length && lines[idx].trim() !== ']') {
+    const line = lines[idx].trim();
+    if (line.length > 0) {
+      const { keyToken, valueToken } = splitPair(line);
+      payload[resolveParamToken(keyToken)] = resolveSwiftValue(valueToken);
+    }
+    idx += 1;
+  }
+  return { payload, endIndex: idx };
+}
+
+function parseObjcDictionary(lines, startIndex) {
+  const payload = {};
+  let idx = startIndex + 1;
+  while (idx < lines.length && lines[idx].trim() !== '} mutableCopy];') {
+    const line = lines[idx].trim();
+    if (line.length > 0) {
+      const { keyToken, valueToken } = splitPair(line);
+      payload[resolveParamToken(keyToken)] = resolveObjcValue(valueToken);
+    }
+    idx += 1;
+  }
+  return { payload, endIndex: idx };
+}
+
+function parseSwiftRuntimePayload(snippet) {
+  const lines = snippet.split('\n');
+  const itemsByName = {};
+  const userProperties = {};
+  let eventName = null;
+  let parameters = null;
+
+  for (let idx = 0; idx < lines.length; idx += 1) {
+    const line = lines[idx].trim();
+    if (!line) continue;
+
+    const itemStart = line.match(/^var (item\d+): \[String: Any\] = \[$/);
+    if (itemStart) {
+      const parsed = parseSwiftDictionary(lines, idx);
+      itemsByName[itemStart[1]] = parsed.payload;
+      idx = parsed.endIndex;
+      continue;
+    }
+
+    const userPropertyMatch = line.match(
+      /^Analytics\.setUserProperty\((.+), forName: (.+)\)$/,
+    );
+    if (userPropertyMatch) {
+      const value = resolveSwiftValue(userPropertyMatch[1].trim());
+      const key = resolveUserPropertyToken(userPropertyMatch[2].trim());
+      userProperties[key] = value === null ? null : String(value);
+      continue;
+    }
+
+    if (line === 'var eventParams: [String: Any] = [') {
+      const parsed = parseSwiftDictionary(lines, idx);
+      parameters = parsed.payload;
+      idx = parsed.endIndex;
+      continue;
+    }
+
+    const itemsAssignmentMatch = line.match(/^eventParams\[(.+)\] = \[(.+)\]$/);
+    if (itemsAssignmentMatch) {
+      const key = resolveParamToken(itemsAssignmentMatch[1].trim());
+      const names = itemsAssignmentMatch[2]
+        .split(',')
+        .map((name) => name.trim())
+        .filter(Boolean);
+      parameters[key] = names.map((name) => itemsByName[name]);
+      continue;
+    }
+
+    const logEventMatch = line.match(
+      /^Analytics\.logEvent\((.+), parameters: (.+)\)$/,
+    );
+    if (logEventMatch) {
+      eventName = resolveEventToken(logEventMatch[1].trim());
+      if (logEventMatch[2].trim() === 'nil') {
+        parameters = null;
+      }
+      continue;
+    }
+  }
+
+  return { eventName, parameters, userProperties };
+}
+
+function parseObjcRuntimePayload(snippet) {
+  const lines = snippet.split('\n');
+  const itemsByName = {};
+  const userProperties = {};
+  let eventName = null;
+  let parameters = null;
+
+  for (let idx = 0; idx < lines.length; idx += 1) {
+    const line = lines[idx].trim();
+    if (!line) continue;
+
+    const itemStart = line.match(/^NSMutableDictionary \*(item\d+) = \[@\{$/);
+    if (itemStart) {
+      const parsed = parseObjcDictionary(lines, idx);
+      itemsByName[itemStart[1]] = parsed.payload;
+      idx = parsed.endIndex;
+      continue;
+    }
+
+    const userPropertyMatch = line.match(
+      /^\[FIRAnalytics setUserPropertyString:(.+) forName:(.+)\];$/,
+    );
+    if (userPropertyMatch) {
+      const value = resolveObjcValue(userPropertyMatch[1].trim());
+      const key = resolveUserPropertyToken(userPropertyMatch[2].trim());
+      userProperties[key] = value === null ? null : String(value);
+      continue;
+    }
+
+    if (line === 'NSMutableDictionary *eventParams = [@{') {
+      const parsed = parseObjcDictionary(lines, idx);
+      parameters = parsed.payload;
+      idx = parsed.endIndex;
+      continue;
+    }
+
+    const itemsAssignmentMatch = line.match(
+      /^eventParams\[(.+)\] = @\[(.+)\];$/,
+    );
+    if (itemsAssignmentMatch) {
+      const key = resolveParamToken(itemsAssignmentMatch[1].trim());
+      const names = itemsAssignmentMatch[2]
+        .split(',')
+        .map((name) => name.trim())
+        .filter(Boolean);
+      parameters[key] = names.map((name) => itemsByName[name]);
+      continue;
+    }
+
+    const logEventMatch = line.match(
+      /^\[FIRAnalytics logEventWithName:(.+) parameters:(.+)\];$/,
+    );
+    if (logEventMatch) {
+      eventName = resolveEventToken(logEventMatch[1].trim());
+      if (logEventMatch[2].trim() === 'nil') {
+        parameters = null;
+      }
+      continue;
+    }
+  }
+
+  return { eventName, parameters, userProperties };
+}
+
+function expectPayloadContract(parsed, expectedContract) {
+  expect(parsed.eventName).toBe(expectedContract.eventName);
+  expect(parsed.parameters || {}).toEqual(expectedContract.parameters || {});
+  expect(parsed.userProperties || {}).toEqual(
+    expectedContract.userProperties || {},
+  );
+}
+
+describe('runtime payload contracts (ios)', () => {
+  it.each(IOS_CONTRACTS)(
+    'validates Swift runtime payload for $id ($class)',
+    (contract) => {
+      const snippet = generateSnippetForTarget({
+        targetId: 'ios-firebase-swift-sdk',
+        example: contract.example,
+        schema: { properties: {} },
+      });
+
+      const parsed = parseSwiftRuntimePayload(snippet);
+      expectPayloadContract(parsed, contract.expected.firebase);
+    },
+  );
+
+  it.each(IOS_CONTRACTS)(
+    'validates Obj-C runtime payload for $id ($class)',
+    (contract) => {
+      const snippet = generateSnippetForTarget({
+        targetId: 'ios-firebase-objc-sdk',
+        example: contract.example,
+        schema: { properties: {} },
+      });
+
+      const parsed = parseObjcRuntimePayload(snippet);
+      expectPayloadContract(parsed, contract.expected.firebase);
+    },
+  );
+});

package/__tests__/runtimePayload.web.test.js

@@ -0,0 +1,32 @@
+const { generateSnippetForTarget } = require('../helpers/snippetTargets');
+const { PAYLOAD_CONTRACTS } = require('../test-data/payloadContracts');
+
+const WEB_CONTRACTS = PAYLOAD_CONTRACTS.filter(
+  (contract) => contract.expected?.web,
+);
+
+function executeWebSnippet(snippet, dataLayerName = 'dataLayer') {
+  const push = jest.fn();
+  const runtimeWindow = {
+    [dataLayerName]: { push },
+  };
+  const runner = new Function('window', snippet);
+  runner(runtimeWindow);
+  return push.mock.calls.map(([payload]) => payload);
+}
+
+describe('runtime payload contracts (web)', () => {
+  it.each(WEB_CONTRACTS)(
+    'validates web payload for $id ($class)',
+    (contract) => {
+      const snippet = generateSnippetForTarget({
+        targetId: 'web-datalayer-js',
+        example: contract.example,
+        schema: { properties: {} },
+      });
+
+      const pushedPayloads = executeWebSnippet(snippet);
+      expect(pushedPayloads).toEqual([contract.expected.web.payload]);
+    },
+  );
+});