《互联网产品的客户端架构·规模化与架构演进》3.1 插件协议与宿主边界

hostApi:
  min: "1.4.0"
  max: "1.9.9"

// file: src/plugin/plugin-protocol.ts
// tier: L1
// verify: node --test test/plugin/plugin-protocol.test.ts

export type Capability =
  | "camera"
  | "location"
  | "network"
  | "storage"
  | "clipboard"
  | "analytics";

export type ApiVersion = { major: number; minor: number; patch: number };

export type PluginManifest = {
  id: string;
  name: string;
  version: string;
  hostApi: { min: string; max: string };
  capabilities: Capability[];
};

export type ManifestResult =
  | { ok: true; manifest: PluginManifest; warnings: string[] }
  | { ok: false; errors: string[] };

export type Compatibility =
  | { status: "compatible"; hostVersion: string }
  | { status: "host-too-old"; required: string; hostVersion: string }
  | { status: "host-too-new"; supported: string; hostVersion: string }
  | { status: "invalid"; reason: string };

export const KNOWN_CAPABILITIES: Capability[] = [
  "camera",
  "location",
  "network",
  "storage",
  "clipboard",
  "analytics",
];

const ID_PATTERN = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/;
const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;

export function parseApiVersion(input: string): ApiVersion | undefined {
  const match = SEMVER_PATTERN.exec(input);
  if (!match) return undefined;
  return {
    major: Number(match[1]),
    minor: Number(match[2]),
    patch: Number(match[3]),
  };
}

export function compareApiVersion(a: ApiVersion, b: ApiVersion): number {
  if (a.major !== b.major) return a.major < b.major ? -1 : 1;
  if (a.minor !== b.minor) return a.minor < b.minor ? -1 : 1;
  if (a.patch !== b.patch) return a.patch < b.patch ? -1 : 1;
  return 0;
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

export function validateManifest(raw: unknown): ManifestResult {
  const errors: string[] = [];
  const warnings: string[] = [];
  if (!isRecord(raw)) return { ok: false, errors: ["清单必须是对象"] };

  const id = raw.id;
  if (typeof id !== "string" || !ID_PATTERN.test(id)) {
    errors.push("id 必须是反向域名格式，例如 com.acme.notes");
  }
  const name = raw.name;
  if (typeof name !== "string" || name.trim() === "") {
    errors.push("name 不能为空");
  }
  const version = raw.version;
  if (typeof version !== "string" || !SEMVER_PATTERN.test(version)) {
    errors.push("version 必须是 x.y.z 形式的语义化版本");
  }

  const hostApi = raw.hostApi;
  let min: ApiVersion | undefined;
  let max: ApiVersion | undefined;
  if (!isRecord(hostApi)) {
    errors.push("hostApi 必须包含 min 与 max");
  } else {
    if (typeof hostApi.min !== "string") {
      errors.push("hostApi.min 必须是字符串");
    } else {
      min = parseApiVersion(hostApi.min);
      if (!min) errors.push("hostApi.min 不是合法版本");
    }
    if (typeof hostApi.max !== "string") {
      errors.push("hostApi.max 必须是字符串");
    } else {
      max = parseApiVersion(hostApi.max);
      if (!max) errors.push("hostApi.max 不是合法版本");
    }
  }
  if (min && max && compareApiVersion(min, max) > 0) {
    errors.push("hostApi.min 不能大于 hostApi.max");
  }
  if (min && max && min.major !== max.major) {
    warnings.push("宿主 API 区间跨主版本，插件需要分别验证");
  }

  const capabilities: Capability[] = [];
  const rawCapabilities = raw.capabilities;
  if (!Array.isArray(rawCapabilities)) {
    errors.push("capabilities 必须是数组");
  } else {
    for (const item of rawCapabilities) {
      if (typeof item !== "string" || !KNOWN_CAPABILITIES.includes(item as Capability)) {
        errors.push(`未知能力: ${String(item)}`);
        continue;
      }
      const capability = item as Capability;
      if (capabilities.includes(capability)) {
        warnings.push(`能力重复声明: ${capability}`);
        continue;
      }
      capabilities.push(capability);
    }
  }

  if (errors.length > 0) return { ok: false, errors };
  const hostRange = hostApi as { min: string; max: string };
  return {
    ok: true,
    manifest: {
      id: id as string,
      name: (name as string).trim(),
      version: version as string,
      hostApi: { min: hostRange.min, max: hostRange.max },
      capabilities,
    },
    warnings,
  };
}

export function checkCompatibility(
  manifest: PluginManifest,
  hostVersion: string,
): Compatibility {
  const host = parseApiVersion(hostVersion);
  if (!host) return { status: "invalid", reason: "宿主版本不是合法语义化版本" };
  const min = parseApiVersion(manifest.hostApi.min);
  const max = parseApiVersion(manifest.hostApi.max);
  if (!min || !max) {
    return { status: "invalid", reason: "插件声明的宿主版本区间非法" };
  }
  if (compareApiVersion(host, min) < 0) {
    return {
      status: "host-too-old",
      required: manifest.hostApi.min,
      hostVersion,
    };
  }
  if (compareApiVersion(host, max) > 0) {
    return {
      status: "host-too-new",
      supported: manifest.hostApi.max,
      hostVersion,
    };
  }
  return { status: "compatible", hostVersion };
}

export function declaredCapabilityGaps(
  manifest: PluginManifest,
  hostCapabilities: Capability[],
): Capability[] {
  return manifest.capabilities.filter(
    (capability) => !hostCapabilities.includes(capability),
  );
}

export type CapabilityAudit = { undeclared: Capability[]; unused: Capability[] };

export function auditCapabilities(
  manifest: PluginManifest,
  used: Capability[],
): CapabilityAudit {
  const undeclared = used.filter(
    (capability) => !manifest.capabilities.includes(capability),
  );
  const unused = manifest.capabilities.filter(
    (capability) => !used.includes(capability),
  );
  return { undeclared, unused };
}

export type ConcernOwner = "host" | "plugin" | "shared" | "unknown";

const CONCERN_OWNERS: Record<string, ConcernOwner> = {
  "lifecycle": "host",
  "route-registration": "host",
  "permission-prompt": "host",
  "crash-report": "host",
  "business-ui": "plugin",
  "data-transform": "plugin",
  "api-client": "shared",
  "storage-schema": "shared",
};

export function ownerOf(concern: string): ConcernOwner {
  return CONCERN_OWNERS[concern] ?? "unknown";
}