@expo-harmony/expo-modules-autolinking 55.0.25-harmony.1

package/src/metadata/host.ts

@@ -0,0 +1,41 @@
+import { HarmonyAutolinkingError } from '../errors';
+import { sortedUniqueStrings } from '../utilities/values';
+
+const ArkTsIdentifierPattern = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const HostMetadataFields = Object.freeze([
+  'rootViewComponents',
+]);
+
+function normalizeIdentifiers(value, field, packageName) {
+  if (value === undefined) return [];
+
+  if (!Array.isArray(value)) {
+    throw new HarmonyAutolinkingError('INVALID_METADATA', `expo-module.config.json#harmony.${field} must be an array.`, {
+      packageName,
+      stage: 'metadata',
+    });
+  }
+  const values = value.map((item, index) => {
+    if (typeof item !== 'string' || !ArkTsIdentifierPattern.test(item)) {
+      throw new HarmonyAutolinkingError('INVALID_METADATA', `harmony.${field}[${index}] must be a valid ArkTS identifier.`, {
+        packageName,
+        stage: 'metadata',
+      });
+    }
+    return item;
+  });
+
+  return sortedUniqueStrings(values);
+}
+
+function normalizeHostMetadata(harmony, record) {
+  return Object.fromEntries(HostMetadataFields.map(field => [
+    field,
+    normalizeIdentifiers(harmony[field], field, record.packageName),
+  ]));
+}
+
+export {
+  HostMetadataFields,
+  normalizeHostMetadata,
+};

package/src/metadata/schema.ts

@@ -0,0 +1,184 @@
+import * as path from 'node:path';
+
+import { HarmonyAutolinkingError } from '../errors';
+import type { HarmonyModuleMetadata, HostMetadata, RnohMetadata } from '../types';
+import { normalizeHostMetadata } from './host';
+import { isObject, requireNonEmptyString } from '../utilities/values';
+
+const ArkTsIdentifierPattern = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const CppIdentifierPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const CmakeTargetPattern = /^[A-Za-z0-9_.:+-]+$/;
+const OhPackagePartPattern = /^[A-Za-z0-9._~-]+$/;
+
+interface MetadataRecord {
+  readonly packageName: string;
+  readonly packageVersion?: string;
+}
+
+type UnknownRecord = Record<string, unknown>;
+
+function metadataError(message: string, record: MetadataRecord): never {
+  throw new HarmonyAutolinkingError('INVALID_METADATA', message, {
+    packageName: record.packageName,
+    stage: 'metadata-normalize',
+  });
+}
+
+function requireObject(value: unknown, message: string, record: MetadataRecord): UnknownRecord {
+  if (!isObject(value)) metadataError(message, record);
+  return value as UnknownRecord;
+}
+
+function isValidOhpmPackageName(value: unknown): value is string {
+  if (typeof value !== 'string' || !value || /[\0\r\n\\'"`;${}()<>\s]/u.test(value)) return false;
+  const scoped = value.startsWith('@');
+  const parts = scoped ? value.slice(1).split('/') : value.split('/');
+  return parts.length === (scoped ? 2 : 1)
+    && parts.every(part => part !== '.' && part !== '..' && OhPackagePartPattern.test(part));
+}
+
+function normalizeOhPackageName(
+  value: unknown,
+  record: MetadataRecord
+): RnohMetadata['ohPackageName'] {
+  if (value === undefined) return undefined;
+  if (typeof value === 'string') {
+    if (!isValidOhpmPackageName(value)) {
+      metadataError('package.json#harmony.autolinking.ohPackageName must be a safe OHPM package name.', record);
+    }
+    return value;
+  }
+  if (!Array.isArray(value)) {
+    metadataError('package.json#harmony.autolinking.ohPackageName must be a string or HAR mapping array.', record);
+  }
+
+  const seen = new Set<string>();
+  return value.map((rawMapping, index) => {
+    const field = `package.json#harmony.autolinking.ohPackageName[${index}]`;
+    const mapping = requireObject(rawMapping, `${field} must be an object.`, record);
+    const harName = requireNonEmptyString(mapping.harName, `${field}.harName`, {
+      packageName: record.packageName,
+      stage: 'metadata-normalize',
+    });
+    if (path.posix.basename(harName) !== harName
+      || path.win32.basename(harName) !== harName
+      || path.posix.extname(harName).toLowerCase() !== '.har') {
+      metadataError(`${field}.harName must be a HAR filename.`, record);
+    }
+    if (seen.has(harName)) metadataError(`${field}.harName is declared more than once.`, record);
+    seen.add(harName);
+    if (!isValidOhpmPackageName(mapping.packageName)) {
+      metadataError(`${field}.packageName must be a safe OHPM package name.`, record);
+    }
+    const version = mapping.version === undefined
+      ? undefined
+      : requireNonEmptyString(mapping.version, `${field}.version`, {
+          packageName: record.packageName,
+          stage: 'metadata-normalize',
+        });
+    return { harName, packageName: mapping.packageName, ...(version ? { version } : {}) };
+  });
+}
+
+function normalizeArkTsModules(value: unknown, record: MetadataRecord): ReadonlyArray<string> {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    metadataError('expo-module.config.json#harmony.modules must be an array.', record);
+  }
+
+  const seen = new Set<string>();
+  const modules = value.map((item, index) => {
+    const moduleClass = requireNonEmptyString(
+      item,
+      `expo-module.config.json#harmony.modules[${index}]`,
+      { packageName: record.packageName, stage: 'metadata-normalize' }
+    );
+    if (!ArkTsIdentifierPattern.test(moduleClass)) {
+      metadataError(`expo-module.config.json#harmony.modules[${index}] must be an ArkTS identifier.`, record);
+    }
+    if (seen.has(moduleClass)) {
+      metadataError(`expo-module.config.json#harmony.modules declares ${moduleClass} more than once.`, record);
+    }
+    seen.add(moduleClass);
+    return moduleClass;
+  });
+  return modules.sort((left, right) => left.localeCompare(right, 'en'));
+}
+
+function normalizeHarmonyModuleMetadata(
+  harmonyValue: unknown,
+  record: MetadataRecord
+): HarmonyModuleMetadata {
+  const harmony = harmonyValue === undefined
+    ? {}
+    : requireObject(harmonyValue, 'expo-module.config.json#harmony must be an object.', record);
+  const host = normalizeHostMetadata(harmony, record) as unknown as HostMetadata;
+  return {
+    ...host,
+    modules: normalizeArkTsModules(harmony.modules, record),
+  };
+}
+
+function optionalIdentifier(
+  value: unknown,
+  field: string,
+  pattern: RegExp,
+  record: MetadataRecord
+): string | undefined {
+  if (value === undefined) return undefined;
+  const normalized = requireNonEmptyString(value, field, {
+    packageName: record.packageName,
+    stage: 'metadata-normalize',
+  });
+  if (!pattern.test(normalized)) metadataError(`${field} is invalid.`, record);
+  return normalized;
+}
+
+/** Normalizes current RNOH package metadata, independently of Expo module config. */
+function normalizeRnohPackageMetadata(
+  value: unknown,
+  record: MetadataRecord
+): Omit<RnohMetadata, 'harPaths'> {
+  if (value == null || value === true) return {};
+  const rnoh = requireObject(value, 'package.json#harmony.autolinking must be an object.', record);
+  const etsPackageImport = rnoh.etsPackageImport;
+  if (etsPackageImport !== undefined && etsPackageImport !== 'default' && etsPackageImport !== 'named') {
+    metadataError('package.json#harmony.autolinking.etsPackageImport must be "default" or "named".', record);
+  }
+  return {
+    ohPackageName: normalizeOhPackageName(rnoh.ohPackageName, record),
+    ...(rnoh.mainHarPath === undefined
+      ? {}
+      : {
+          mainHarPath: requireNonEmptyString(rnoh.mainHarPath, 'package.json#harmony.autolinking.mainHarPath', {
+            packageName: record.packageName,
+            stage: 'metadata-normalize',
+          }),
+        }),
+    etsPackageClassName: optionalIdentifier(
+      rnoh.etsPackageClassName,
+      'package.json#harmony.autolinking.etsPackageClassName',
+      ArkTsIdentifierPattern,
+      record
+    ),
+    etsPackageImport: etsPackageImport as 'default' | 'named' | undefined,
+    cppPackageClassName: optionalIdentifier(
+      rnoh.cppPackageClassName,
+      'package.json#harmony.autolinking.cppPackageClassName',
+      CppIdentifierPattern,
+      record
+    ),
+    cmakeLibraryTargetName: optionalIdentifier(
+      rnoh.cmakeLibraryTargetName,
+      'package.json#harmony.autolinking.cmakeLibraryTargetName',
+      CmakeTargetPattern,
+      record
+    ),
+  };
+}
+
+export {
+  isValidOhpmPackageName,
+  normalizeHarmonyModuleMetadata,
+  normalizeRnohPackageMetadata,
+};

package/src/types.ts

@@ -0,0 +1,220 @@
+export type Platform = 'harmony';
+export type BuildType = 'debug' | 'release';
+export type ModuleSource
+  = 'dependency'
+    | 'searchPath'
+    | 'nativeModulesDir'
+    | 'reactNativeProjectConfig';
+
+export interface ArkTsModulePackage {
+  /** Conventional package-relative HAR exporting the ArkTS module classes. */
+  readonly harPath: string;
+  /** OHPM package name read from the Harmony library manifest. */
+  readonly ohPackageName: string;
+}
+
+export interface HostMetadata {
+  readonly rootViewComponents: ReadonlyArray<string>;
+}
+
+export type ExpoMetadata = HostMetadata;
+
+export interface RnohMetadata {
+  readonly ohPackageName?: string | ReadonlyArray<{
+    readonly harName: string;
+    readonly packageName: string;
+    readonly version?: string;
+  }>;
+  readonly mainHarPath?: string;
+  readonly harPaths: ReadonlyArray<string>;
+  readonly etsPackageClassName?: string;
+  readonly etsPackageImport?: 'default' | 'named';
+  readonly cppPackageClassName?: string;
+  readonly cmakeLibraryTargetName?: string;
+}
+
+export interface HarmonyModuleMetadata extends HostMetadata {
+  /** ArkTS Module classes exported by the conventional Harmony library. */
+  readonly modules: ReadonlyArray<string>;
+}
+
+export interface FixedHvigorBuildDescriptor {
+  readonly executable: 'hvigorw';
+  readonly cwd: string;
+  readonly args: ReadonlyArray<string>;
+}
+
+export type ModuleArtifactDescriptor = {
+  readonly kind: 'bundled';
+  readonly harPaths: ReadonlyArray<string>;
+} | {
+  readonly kind: 'local-source';
+  readonly outputPath: string;
+  readonly materialized: false;
+  readonly build: FixedHvigorBuildDescriptor;
+};
+
+export interface ModuleDescriptor {
+  readonly packageName: string;
+  readonly packageVersion: string;
+  readonly packageRoot: string;
+  /** Reachable package path used to install the bundled HAR during a native build. */
+  readonly packageLinkPath: string;
+  readonly source: ModuleSource;
+  /** Host extension declarations consumed by the generated application provider. */
+  readonly expo: ExpoMetadata;
+  /** RNOH package metadata read from package.json#harmony.autolinking. */
+  readonly rnoh: RnohMetadata;
+  /** Expo module author metadata from expo-module.config.json#harmony. */
+  readonly harmony: HarmonyModuleMetadata;
+  /** Build/package data derived from the conventional Harmony project, never author config. */
+  readonly arkTs?: ArkTsModulePackage;
+  readonly artifact: ModuleArtifactDescriptor;
+}
+
+export interface SearchRecord {
+  readonly packageName: string;
+  readonly packageVersion: string;
+  readonly packageRoot: string;
+  readonly source: ModuleSource;
+  readonly supportsHarmony: boolean;
+  readonly expoModuleConfig: Readonly<Record<string, unknown>> | null;
+  readonly rnohMetadata: unknown;
+  readonly revision: {
+    readonly depth: number | null;
+    readonly originPath: string;
+  };
+}
+
+export interface SearchResult {
+  readonly platform: Platform;
+  readonly modules: ReadonlyArray<SearchRecord>;
+  readonly duplicates: ReadonlyArray<{
+    readonly packageName: string;
+    readonly revisions: ReadonlyArray<{ readonly version: string; readonly path: string }>;
+  }>;
+  readonly missingIncludes: ReadonlyArray<string>;
+  readonly options: {
+    readonly projectRoot: string;
+    readonly searchPaths: ReadonlyArray<string>;
+    readonly nativeModulesDir: string | null;
+    readonly exclude: ReadonlyArray<string>;
+    readonly include: ReadonlyArray<string>;
+    readonly buildType: BuildType;
+  };
+}
+
+export interface DiagnosticSource {
+  readonly packageName: string;
+  readonly packageVersion: string;
+  readonly packageRoot: string;
+  readonly field?: string;
+}
+
+export interface Diagnostic {
+  readonly severity: 'error' | 'warning';
+  readonly code: string;
+  readonly message: string;
+  readonly packageName?: string;
+  readonly stage: string;
+  readonly sources?: ReadonlyArray<DiagnosticSource>;
+}
+
+export interface VerificationResult {
+  readonly valid: boolean;
+  readonly diagnostics: ReadonlyArray<Diagnostic>;
+  readonly modules: ReadonlyArray<ModuleDescriptor>;
+}
+
+export interface Manifest {
+  readonly schemaVersion: 3;
+  readonly platform: 'harmony';
+  readonly buildType: BuildType;
+  readonly modules: ReadonlyArray<ModuleDescriptor>;
+  readonly managedArtifacts: ReadonlyArray<string>;
+}
+
+export interface CanonicalizeAutolinkingArtifactsOptions {
+  readonly manifestSource: string;
+  readonly ohPackageSource: string;
+  readonly generatedProjectRoot: string;
+  readonly canonicalProjectRoot: string;
+  readonly harmonyProjectPath?: string;
+}
+
+export interface CanonicalizedAutolinkingArtifacts {
+  readonly manifest: Manifest;
+  readonly manifestSource: string;
+  readonly ohPackageSource: string;
+}
+
+export interface Logger {
+  debug?(message: string, details?: unknown): void;
+  info?(message: string, details?: unknown): void;
+  warn?(message: string, details?: unknown): void;
+  error?(message: string, details?: unknown): void;
+}
+
+export interface SearchOptions {
+  projectRoot?: string;
+  platform?: Platform;
+  searchPaths?: ReadonlyArray<string>;
+  nativeModulesDir?: string | null;
+  exclude?: ReadonlyArray<string>;
+  include?: ReadonlyArray<string>;
+  buildType?: BuildType;
+  logger?: Logger;
+}
+
+export interface ResolveOptions extends SearchOptions {
+  searchResult?: SearchResult;
+}
+
+export interface VerifyOptions extends ResolveOptions {
+  modules?: ReadonlyArray<ModuleDescriptor>;
+}
+
+export interface LinkOptions extends VerifyOptions {
+  projectRoot: string;
+  harmonyProjectPath: string;
+  nodeModulesPath?: string;
+  reactNativeExecutable?: string;
+  rnohCliPackageJsonPath?: string;
+  timeoutMs?: number;
+  outputLimit?: number;
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface MaterializeLocalSourceOptions {
+  readonly projectRoot: string;
+  readonly module: ModuleDescriptor;
+  readonly timeoutMs?: number;
+  readonly outputLimit?: number;
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+export interface MaterializedLocalSource {
+  readonly packageName: string;
+  readonly harPath: string;
+}
+
+export interface LinkResult {
+  readonly platform: Platform;
+  readonly modules: ReadonlyArray<ModuleDescriptor>;
+  readonly buildType: BuildType;
+  readonly managedArtifacts: ReadonlyArray<string>;
+  readonly changedArtifacts: ReadonlyArray<string>;
+  readonly unchangedArtifacts: ReadonlyArray<string>;
+  readonly diagnostics: ReadonlyArray<Diagnostic>;
+  readonly warnings: ReadonlyArray<Diagnostic>;
+}
+
+export interface AutolinkingErrorJson {
+  readonly name: 'HarmonyAutolinkingError';
+  readonly code: string;
+  readonly message: string;
+  readonly stage: string;
+  readonly packageName?: string;
+  readonly diagnostics?: ReadonlyArray<Diagnostic>;
+  readonly details?: unknown;
+}

package/src/utilities/values.ts

@@ -0,0 +1,190 @@
+import { createRequire } from 'node:module';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { HarmonyAutolinkingError } from '../errors';
+
+function isObject(value) {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function compareText(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function sortedUniqueStrings(items: ReadonlyArray<string>): string[] {
+  return [...new Set(items)].sort(compareText);
+}
+
+function uniqueStrings(items: ReadonlyArray<string>): string[] {
+  return [...new Set(items)];
+}
+
+function stringifyJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function normalizeSlashes(value) {
+  return value.split(path.sep).join('/');
+}
+
+async function readJsonAsync(file, code = 'INVALID_METADATA', stage = 'metadata') {
+  try {
+    return JSON.parse(await fs.promises.readFile(file, 'utf8'));
+  } catch (cause) {
+    throw new HarmonyAutolinkingError(code, `Unable to read valid JSON from ${file}.`, { cause, stage });
+  }
+}
+
+async function pathExistsAsync(target) {
+  try {
+    await fs.promises.access(target);
+    return true;
+  } catch (_cause) {
+    return false;
+  }
+}
+
+function resolvePackageFromProject(projectRoot, specifier) {
+  return createRequire(path.join(projectRoot, 'package.json')).resolve(specifier);
+}
+
+function isPathInside(parent, child) {
+  const relative = path.relative(parent, child);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function realpathExistingAsync(target, options: Record<string, any> = {}) {
+  const type = options.type || 'path';
+  const code = options.code || 'INVALID_OPTIONS';
+  const stage = options.stage || 'validation';
+  const field = options.field || 'path';
+
+  try {
+    const resolved = await fs.promises.realpath(path.resolve(target));
+    const stat = await fs.promises.stat(resolved);
+
+    if (type === 'directory' && !stat.isDirectory()) throw new TypeError('not a directory');
+    if (type === 'file' && !stat.isFile()) throw new TypeError('not a file');
+    return resolved;
+  } catch (cause) {
+    throw new HarmonyAutolinkingError(code, `${field} does not reference an existing ${type}: ${target}`, {
+      cause,
+      stage,
+    });
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function resolveInsideAsync(root, relative, field, options: Record<string, any> = {}) {
+  const mustExist = options.mustExist !== false;
+  const type = options.type || 'path';
+  const packageName = options.packageName;
+
+  if (typeof relative !== 'string' || !relative.trim() || path.isAbsolute(relative)) {
+    throw new HarmonyAutolinkingError('INVALID_METADATA', `${field} must be a non-empty package-relative path.`, {
+      packageName,
+      stage: 'metadata',
+    });
+  }
+  const realRoot = await fs.promises.realpath(root);
+  const lexical = path.resolve(realRoot, relative);
+
+  if (!isPathInside(realRoot, lexical)) {
+    throw new HarmonyAutolinkingError('PATH_OUTSIDE_PACKAGE', `${field} escapes package root.`, {
+      packageName,
+      stage: 'metadata',
+    });
+  }
+  if (!mustExist) return lexical;
+
+  let resolved;
+  try {
+    resolved = await fs.promises.realpath(lexical);
+  } catch (cause) {
+    throw new HarmonyAutolinkingError('INVALID_METADATA', `${field} does not exist: ${relative}`, {
+      cause,
+      packageName,
+      stage: 'metadata',
+    });
+  }
+
+  if (!isPathInside(realRoot, resolved)) {
+    throw new HarmonyAutolinkingError('PATH_OUTSIDE_PACKAGE', `${field} resolves outside package root.`, {
+      packageName,
+      stage: 'metadata',
+    });
+  }
+  const stat = await fs.promises.stat(resolved);
+
+  if (type === 'file' && !stat.isFile()) {
+    throw new HarmonyAutolinkingError('INVALID_METADATA', `${field} must reference a file: ${relative}`, {
+      packageName,
+      stage: 'metadata',
+    });
+  }
+  if (type === 'directory' && !stat.isDirectory()) {
+    throw new HarmonyAutolinkingError('INVALID_METADATA', `${field} must reference a directory: ${relative}`, {
+      packageName,
+      stage: 'metadata',
+    });
+  }
+  return resolved;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function requireNonEmptyString(value, field, options: Record<string, any> = {}) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new HarmonyAutolinkingError(options.code || 'INVALID_METADATA', `${field} must be a non-empty string.`, {
+      packageName: options.packageName,
+      stage: options.stage || 'metadata',
+    });
+  }
+  return value;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function normalizeStringArray(value, field, options: Record<string, any> = {}) {
+  if (value == null && options.optional) return [];
+
+  const values = Array.isArray(value) ? value : options.allowScalar ? [value] : null;
+  if (!values || values.some(item => typeof item !== 'string' || !item.trim())) {
+    throw new HarmonyAutolinkingError(options.code || 'INVALID_OPTIONS', `${field} must be an array of non-empty strings.`, {
+      packageName: options.packageName,
+      stage: options.stage || 'options',
+    });
+  }
+
+  return [...new Set(values)];
+}
+
+function sanitizeOutput(value, roots = [], limit = 8192) {
+  let result = String(value || '');
+
+  for (const root of roots.filter(Boolean)) result = result.split(root).join('<path>');
+  return result.slice(0, limit);
+}
+
+function emitLog(logger, level, message, details) {
+  if (logger && typeof logger[level] === 'function') logger[level](message, details);
+}
+
+export {
+  compareText,
+  emitLog,
+  isObject,
+  isPathInside,
+  normalizeSlashes,
+  pathExistsAsync,
+  resolvePackageFromProject,
+  readJsonAsync,
+  realpathExistingAsync,
+  requireNonEmptyString,
+  resolveInsideAsync,
+  sanitizeOutput,
+  stringifyJson,
+  sortedUniqueStrings,
+  normalizeStringArray,
+  uniqueStrings,
+};

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "esModuleInterop": true,
+    "lib": ["ES2022"],
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "build",
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noImplicitAny": false,
+    "strictNullChecks": false,
+    "useUnknownInCatchVariables": false,
+    "target": "ES2022",
+    "types": ["node"]
+  },
+  "include": [
+    "bin/**/*.ts",
+    "index.ts",
+    "src/**/*.ts"
+  ],
+  "exclude": ["build"]
+}