@expo/fingerprint 0.0.1

package/src/Dedup.ts

@@ -0,0 +1,97 @@
+import assert from 'assert';
+import path from 'path';
+
+import type { HashSource, HashSourceDir, HashSourceFile } from './Fingerprint.types';
+
+const debug = require('debug')('expo:fingerprint:Dedup');
+
+/**
+ * Strip duplicated sources, mainly for duplicated file or dir
+ */
+export function dedupSources(sources: HashSource[], projectRoot: string): HashSource[] {
+  const newSources: HashSource[] = [];
+  for (const source of sources) {
+    const [duplicatedItemIndex, shouldSwapSource] = findDuplicatedSourceIndex(
+      newSources,
+      source,
+      projectRoot
+    );
+    if (duplicatedItemIndex >= 0) {
+      const duplicatedItem = newSources[duplicatedItemIndex];
+      debug(`Skipping duplicated source: ${source}`);
+      if (shouldSwapSource) {
+        newSources[duplicatedItemIndex] = {
+          ...source,
+          reasons: [...source.reasons, ...duplicatedItem.reasons],
+        };
+      } else {
+        duplicatedItem.reasons.push(...source.reasons);
+      }
+    } else {
+      newSources.push(source);
+    }
+  }
+
+  return newSources;
+}
+
+/**
+ * When two sources are duplicated, merge `src`'s reasons into `dst`
+ */
+export function mergeSourceWithReasons(dst: HashSource, src: HashSource): HashSource {
+  return dst;
+}
+
+/**
+ * Find the duplicated `source` in `newSources`
+ * @return tuple of [duplicatedItemIndexInNewSources, shouldSwapSource]
+ */
+function findDuplicatedSourceIndex(
+  newSources: HashSource[],
+  source: HashSource,
+  projectRoot: string
+): [number, boolean] {
+  let shouldSwapSource = false;
+  if (source.type === 'contents') {
+    return [
+      newSources.findIndex((item) => item.type === source.type && item.id === source.id) ?? null,
+      shouldSwapSource,
+    ];
+  }
+
+  for (const [index, existingSource] of newSources.entries()) {
+    if (existingSource.type === 'contents') {
+      continue;
+    }
+    if (isDescendant(source, existingSource, projectRoot)) {
+      return [index, shouldSwapSource];
+    }
+    // If the new source is ancestor of existing source, replace swap the existing source with the new source
+    if (isDescendant(existingSource, source, projectRoot)) {
+      shouldSwapSource = true;
+      return [index, shouldSwapSource];
+    }
+  }
+  return [-1, shouldSwapSource];
+}
+
+function isDescendant(
+  from: HashSourceDir | HashSourceFile,
+  to: HashSourceDir | HashSourceFile,
+  projectRoot: string
+): boolean {
+  if (from === to) {
+    return true;
+  }
+
+  const fromPath = path.join(projectRoot, from.filePath);
+  const toPath = path.join(projectRoot, to.filePath);
+  const result = path.relative(fromPath, toPath).match(/^[./\\/]*$/) != null;
+  if (result) {
+    assert(
+      !(to.type === 'file' && from.type === 'dir'),
+      `Unexpected case which a dir is a descendant of a file - from[${fromPath}] to[${toPath}]`
+    );
+  }
+  return result;
+}

package/src/Fingerprint.ts

@@ -0,0 +1,51 @@
+import { dedupSources } from './Dedup';
+import type { Fingerprint, FingerprintSource, Options } from './Fingerprint.types';
+import { normalizeOptions } from './Options';
+import { sortSources } from './Sort';
+import { createFingerprintFromSourcesAsync } from './hash/Hash';
+import { getHashSourcesAsync } from './sourcer/Sourcer';
+
+/**
+ * Create a fingerprint from project
+ */
+export async function createFingerprintAsync(
+  projectRoot: string,
+  options?: Options
+): Promise<Fingerprint> {
+  const opts = normalizeOptions(options);
+  const sources = await getHashSourcesAsync(projectRoot, opts);
+  const normalizedSources = sortSources(dedupSources(sources, projectRoot));
+  const fingerprint = await createFingerprintFromSourcesAsync(normalizedSources, projectRoot, opts);
+  return fingerprint;
+}
+
+/**
+ * Create a native hash value from project
+ */
+export async function createProjectHashAsync(
+  projectRoot: string,
+  options?: Options
+): Promise<string> {
+  const fingerprint = await createFingerprintAsync(projectRoot, options);
+  return fingerprint.hash;
+}
+
+/**
+ * Differentiate given `fingerprint` with the current project fingerprint state
+ */
+export async function diffFingerprintChangesAsync(
+  fingerprint: Fingerprint,
+  projectRoot: string,
+  options?: Options
+): Promise<FingerprintSource[]> {
+  const newFingerprint = await createFingerprintAsync(projectRoot, options);
+  if (fingerprint.hash === newFingerprint.hash) {
+    return [];
+  }
+  const result: FingerprintSource[] = newFingerprint.sources.filter((newItem) => {
+    return !fingerprint.sources.find(
+      (item) => item.type === newItem.type && item.hash === newItem.hash
+    );
+  });
+  return result;
+}

package/src/Fingerprint.types.ts

@@ -0,0 +1,98 @@
+export type FingerprintSource = HashSource & {
+  /**
+   * Hash value of the `source`.
+   * If the source is excluding by `Options.dirExcludes`, the value will be null.
+   */
+  hash: string | null;
+};
+
+export interface Fingerprint {
+  /**
+   * Sources and their hash values to generate a fingerprint
+   */
+  sources: FingerprintSource[];
+
+  /**
+   * The final hash value of the whole fingerprint
+   */
+  hash: string;
+}
+
+export type Platform = 'android' | 'ios';
+
+export interface Options {
+  /**
+   * Only get native files from the given platforms. Default is `['android', 'ios']`.
+   */
+  platforms?: Platform[];
+
+  /**
+   * I/O concurrent limit. Default is the number of CPU core.
+   */
+  concurrentIoLimit?: number;
+
+  /**
+   * The algorithm passing to `crypto.createHash()`. Default is `'sha1'`.
+   */
+  hashAlgorithm?: string;
+
+  /**
+   * Excludes directories from hashing. This supported pattern is as `glob()`.
+   * Default is `['android/build', 'android/app/build', 'android/app/.cxx', 'ios/Pods']`.
+   */
+  dirExcludes?: string[];
+
+  /**
+   * Additional sources for hashing.
+   */
+  extraSources?: HashSource[];
+}
+
+//#region internal types
+
+export interface NormalizedOptions extends Options {
+  platforms: NonNullable<Options['platforms']>;
+  concurrentIoLimit: NonNullable<Options['concurrentIoLimit']>;
+  hashAlgorithm: NonNullable<Options['hashAlgorithm']>;
+  dirExcludes: NonNullable<Options['dirExcludes']>;
+}
+
+export interface HashSourceFile {
+  type: 'file';
+  filePath: string;
+
+  /**
+   * Reasons of this source coming from
+   */
+  reasons: string[];
+}
+
+export interface HashSourceDir {
+  type: 'dir';
+  filePath: string;
+
+  /**
+   * Reasons of this source coming from
+   */
+  reasons: string[];
+}
+
+export interface HashSourceContents {
+  type: 'contents';
+  id: string;
+  contents: string | Buffer;
+
+  /**
+   * Reasons of this source coming from
+   */
+  reasons: string[];
+}
+
+export type HashSource = HashSourceFile | HashSourceDir | HashSourceContents;
+
+export interface HashResult {
+  id: string;
+  hex: string;
+}
+
+//#endregion

package/src/Options.ts

@@ -0,0 +1,18 @@
+import os from 'os';
+
+import type { NormalizedOptions, Options } from './Fingerprint.types';
+
+export function normalizeOptions(options?: Options): NormalizedOptions {
+  return {
+    ...options,
+    platforms: options?.platforms ?? ['android', 'ios'],
+    concurrentIoLimit: options?.concurrentIoLimit ?? os.cpus().length,
+    hashAlgorithm: options?.hashAlgorithm ?? 'sha1',
+    dirExcludes: options?.dirExcludes ?? [
+      '**/android/build',
+      '**/android/app/build',
+      '**/android/app/.cxx',
+      'ios/Pods',
+    ],
+  };
+}

package/src/Sort.ts

@@ -0,0 +1,22 @@
+import type { HashSource } from './Fingerprint.types';
+
+export function sortSources<T extends HashSource>(sources: T[]): T[] {
+  const typeOrder = {
+    file: 0,
+    dir: 1,
+    contents: 2,
+  };
+  return sources.sort((a, b) => {
+    const typeResult = typeOrder[a.type] - typeOrder[b.type];
+    if (typeResult === 0) {
+      if (a.type === 'file' && b.type === 'file') {
+        return a.filePath.localeCompare(b.filePath);
+      } else if (a.type === 'dir' && b.type === 'dir') {
+        return a.filePath.localeCompare(b.filePath);
+      } else if (a.type === 'contents' && b.type === 'contents') {
+        return a.id.localeCompare(b.id);
+      }
+    }
+    return typeResult;
+  });
+}

package/src/__tests__/Dedup-test.ts

@@ -0,0 +1,177 @@
+import { dedupSources } from '../Dedup';
+import type { HashSource } from '../Fingerprint.types';
+
+describe(dedupSources, () => {
+  it('should dedup descendant dir - ancestor coming first', () => {
+    const sources: HashSource[] = [
+      {
+        type: 'dir',
+        filePath: 'android',
+        reasons: ['root'],
+      },
+      {
+        type: 'dir',
+        filePath: 'android/app',
+        reasons: ['subfolder'],
+      },
+    ];
+
+    expect(dedupSources(sources, '/app')).toEqual([
+      {
+        type: 'dir',
+        filePath: 'android',
+        reasons: ['root', 'subfolder'],
+      },
+    ]);
+  });
+
+  it('should dedup descendant dir - ancestor coming later', () => {
+    const sources: HashSource[] = [
+      {
+        type: 'dir',
+        filePath: 'android/app',
+        reasons: ['subfolder'],
+      },
+      {
+        type: 'dir',
+        filePath: 'android',
+        reasons: ['root'],
+      },
+    ];
+
+    expect(dedupSources(sources, '/app')).toEqual([
+      {
+        type: 'dir',
+        filePath: 'android',
+        reasons: ['root', 'subfolder'],
+      },
+    ]);
+  });
+
+  it('should dedup descendant file - file coming first', () => {
+    const sources: HashSource[] = [
+      {
+        type: 'file',
+        filePath: 'android/app/build.gradle',
+        reasons: ['file'],
+      },
+      {
+        type: 'dir',
+        filePath: 'android',
+        reasons: ['root'],
+      },
+    ];
+
+    expect(dedupSources(sources, '/app')).toEqual([
+      {
+        type: 'dir',
+        filePath: 'android',
+        reasons: ['root', 'file'],
+      },
+    ]);
+  });
+
+  it('should dedup descendant file - file coming later', () => {
+    const sources: HashSource[] = [
+      {
+        type: 'dir',
+        filePath: 'android',
+        reasons: ['root'],
+      },
+      {
+        type: 'file',
+        filePath: 'android/app/build.gradle',
+        reasons: ['file'],
+      },
+    ];
+
+    expect(dedupSources(sources, '/app')).toEqual([
+      {
+        type: 'dir',
+        filePath: 'android',
+        reasons: ['root', 'file'],
+      },
+    ]);
+  });
+
+  it('should dedup slibings dir', () => {
+    const sources: HashSource[] = [
+      {
+        type: 'dir',
+        filePath: 'node_modules/expo',
+        reasons: ['expo'],
+      },
+      {
+        type: 'dir',
+        filePath: 'node_modules/expo-modules-core',
+        reasons: ['expo-modules-core'],
+      },
+    ];
+
+    expect(dedupSources(sources, '/app')).toEqual([
+      {
+        type: 'dir',
+        filePath: 'node_modules/expo',
+        reasons: ['expo'],
+      },
+      {
+        type: 'dir',
+        filePath: 'node_modules/expo-modules-core',
+        reasons: ['expo-modules-core'],
+      },
+    ]);
+  });
+
+  it('should keep unique contents by its id', () => {
+    const sources: HashSource[] = [
+      {
+        type: 'contents',
+        id: 'foo',
+        contents: 'foo:1',
+        reasons: ['foo:1'],
+      },
+      {
+        type: 'dir',
+        filePath: 'android',
+        reasons: ['root'],
+      },
+      {
+        type: 'contents',
+        id: 'foo',
+        contents: 'foo:2',
+        reasons: ['foo:2'],
+      },
+    ];
+
+    expect(dedupSources(sources, '/app')).toEqual([
+      {
+        type: 'contents',
+        id: 'foo',
+        contents: 'foo:1',
+        reasons: ['foo:1', 'foo:2'],
+      },
+      {
+        type: 'dir',
+        filePath: 'android',
+        reasons: ['root'],
+      },
+    ]);
+  });
+
+  it('should throw error when a dir is descendant of a file', () => {
+    const sources: HashSource[] = [
+      {
+        type: 'file',
+        filePath: 'android',
+        reasons: ['file'],
+      },
+      {
+        type: 'dir',
+        filePath: 'android/app',
+        reasons: ['dir'],
+      },
+    ];
+
+    expect(() => dedupSources(sources, '/app')).toThrow();
+  });
+});

package/src/__tests__/Fingerprint-test.ts

@@ -0,0 +1,116 @@
+import { vol } from 'memfs';
+
+import { createFingerprintAsync, diffFingerprintChangesAsync } from '../Fingerprint';
+import type { Fingerprint } from '../Fingerprint.types';
+import { normalizeOptions } from '../Options';
+
+jest.mock('fs');
+jest.mock('fs/promises');
+
+describe(diffFingerprintChangesAsync, () => {
+  afterEach(() => {
+    vol.reset();
+  });
+
+  it('should return empty array when fingerprint matched', async () => {
+    vol.fromJSON(require('../sourcer/__tests__/fixtures/ExpoManaged47Project.json'));
+    const fingerprint = await createFingerprintAsync('/app', normalizeOptions());
+    const diff = await diffFingerprintChangesAsync(fingerprint, '/app', normalizeOptions());
+    expect(diff.length).toBe(0);
+  });
+
+  it('should return diff from new item', async () => {
+    vol.fromJSON(require('../sourcer/__tests__/fixtures/ExpoManaged47Project.json'));
+    const fingerprint: Fingerprint = {
+      sources: [],
+      hash: '',
+    };
+
+    const diff = await diffFingerprintChangesAsync(fingerprint, '/app', normalizeOptions());
+    expect(diff).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "filePath": "app.json",
+          "hash": "1fd2d92d50dc1da96b41795046b9ea4e30dd2b48",
+          "reasons": Array [
+            "expoConfig",
+          ],
+          "type": "file",
+        },
+      ]
+    `);
+  });
+
+  it('should return diff from contents changes', async () => {
+    vol.fromJSON(require('../sourcer/__tests__/fixtures/ExpoManaged47Project.json'));
+    const packageJson = JSON.parse(vol.readFileSync('/app/package.json', 'utf8').toString());
+    jest.doMock('/app/package.json', () => packageJson, { virtual: true });
+    const fingerprint = await createFingerprintAsync('/app', normalizeOptions());
+
+    // first round for bumping package version which should not cause changes
+    packageJson.version = '111.111.111';
+    jest.doMock('/app/package.json', () => packageJson, { virtual: true });
+    let diff = await diffFingerprintChangesAsync(fingerprint, '/app', normalizeOptions());
+    expect(diff.length).toBe(0);
+
+    // second round to update scripts section and it should cause changes
+    packageJson.scripts ||= {};
+    packageJson.scripts.postinstall = 'echo "hello"';
+    jest.doMock('/app/package.json', () => packageJson, { virtual: true });
+    diff = await diffFingerprintChangesAsync(fingerprint, '/app', normalizeOptions());
+    jest.dontMock('/app/package.json');
+    expect(diff).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "contents": "{\\"start\\":\\"expo start\\",\\"android\\":\\"expo start --android\\",\\"ios\\":\\"expo start --ios\\",\\"web\\":\\"expo start --web\\",\\"postinstall\\":\\"echo \\\\\\"hello\\\\\\"\\"}",
+          "hash": "47f4d7bae018eb17440153f09977113501eace30",
+          "id": "packageJson:scripts",
+          "reasons": Array [
+            "packageJson:scripts",
+          ],
+          "type": "contents",
+        },
+      ]
+    `);
+  });
+
+  it('should return diff from file changes', async () => {
+    vol.fromJSON(require('../sourcer/__tests__/fixtures/ExpoManaged47Project.json'));
+    const fingerprint = await createFingerprintAsync('/app', normalizeOptions());
+    const config = JSON.parse(vol.readFileSync('/app/app.json', 'utf8').toString());
+    config.expo.jsEngine = 'jsc';
+    vol.writeFileSync('/app/app.json', JSON.stringify(config, null, 2));
+    const diff = await diffFingerprintChangesAsync(fingerprint, '/app', normalizeOptions());
+    expect(diff).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "filePath": "app.json",
+          "hash": "9ff1b51ca9b9435e8b849bcc82e3900d70f0feee",
+          "reasons": Array [
+            "expoConfig",
+          ],
+          "type": "file",
+        },
+      ]
+    `);
+  });
+
+  it('should return diff from dir changes', async () => {
+    vol.fromJSON(require('../sourcer/__tests__/fixtures/BareReactNative70Project.json'));
+    const fingerprint = await createFingerprintAsync('/app', normalizeOptions());
+    vol.writeFileSync('/app/ios/README.md', '# Adding new file in ios dir');
+    const diff = await diffFingerprintChangesAsync(fingerprint, '/app', normalizeOptions());
+    expect(diff).toMatchInlineSnapshot(`
+      Array [
+        Object {
+          "filePath": "ios",
+          "hash": "e4190c0af9142fe4add4842777d9aec713213cd4",
+          "reasons": Array [
+            "bareNativeDir",
+          ],
+          "type": "dir",
+        },
+      ]
+    `);
+  });
+});

package/src/__tests__/Sort-test.ts

@@ -0,0 +1,56 @@
+import type { FingerprintSource, HashSource } from '../Fingerprint.types';
+import { sortSources } from '../Sort';
+
+describe(sortSources, () => {
+  it(`should sort sources by type in 'file > dir > contents' order`, () => {
+    const sources: HashSource[] = [
+      { type: 'contents', id: 'foo', contents: 'HelloWorld', reasons: ['foo'] },
+      { type: 'file', filePath: '/app/app.json', reasons: ['expoConfig'] },
+      { type: 'dir', filePath: '/app/ios', reasons: ['bareNativeDir'] },
+    ];
+
+    expect(sortSources(sources)).toEqual([
+      { type: 'file', filePath: '/app/app.json', reasons: ['expoConfig'] },
+      { type: 'dir', filePath: '/app/ios', reasons: ['bareNativeDir'] },
+      { type: 'contents', id: 'foo', contents: 'HelloWorld', reasons: ['foo'] },
+    ]);
+  });
+
+  it(`should sort id or filePath when item types are the same`, () => {
+    const sources: HashSource[] = [
+      { type: 'file', filePath: '/app/eas.json', reasons: ['easBuild'] },
+      { type: 'contents', id: 'foo', contents: 'HelloWorld', reasons: ['foo'] },
+      { type: 'dir', filePath: '/app/ios', reasons: ['bareNativeDir'] },
+      { type: 'file', filePath: '/app/app.json', reasons: ['expoConfig'] },
+      { type: 'contents', id: 'bar', contents: 'bartender', reasons: ['bar'] },
+      { type: 'dir', filePath: '/app/android', reasons: ['bareNativeDir'] },
+    ];
+
+    expect(sortSources(sources)).toEqual([
+      { type: 'file', filePath: '/app/app.json', reasons: ['expoConfig'] },
+      { type: 'file', filePath: '/app/eas.json', reasons: ['easBuild'] },
+      { type: 'dir', filePath: '/app/android', reasons: ['bareNativeDir'] },
+      { type: 'dir', filePath: '/app/ios', reasons: ['bareNativeDir'] },
+      { type: 'contents', id: 'bar', contents: 'bartender', reasons: ['bar'] },
+      { type: 'contents', id: 'foo', contents: 'HelloWorld', reasons: ['foo'] },
+    ]);
+  });
+
+  it(`should support both HashSource and FingerprintSource types`, () => {
+    const sources: HashSource[] = [
+      { type: 'contents', id: 'foo', contents: 'HelloWorld', reasons: ['foo'] },
+    ];
+    const fingerprintSources: FingerprintSource[] = [
+      {
+        type: 'contents',
+        id: 'foo',
+        contents: 'HelloWorld',
+        reasons: ['foo'],
+        hash: 'bc9faaae1e35d52f3dea9651da12cd36627b8403',
+      },
+    ];
+
+    expect(sortSources(sources)).toEqual(sources);
+    expect(sortSources(fingerprintSources)).toEqual(fingerprintSources);
+  });
+});