@epicdm/flowstate-extension-core 1.0.0

package/dist/index.js

@@ -0,0 +1,1042 @@
+'use strict';
+
+var fflate = require('fflate');
+
+// src/manifest-adapter.ts
+var CATEGORY_MAP = {
+  "Azure": "azure",
+  "Data Science": "data-science",
+  "Debuggers": "debuggers",
+  "Education": "education",
+  "Extension Packs": "extension-packs",
+  "Formatters": "formatters",
+  "Keymaps": "keymaps",
+  "Language Packs": "language-packs",
+  "Linters": "linters",
+  "Machine Learning": "machine-learning",
+  "Notebooks": "notebooks",
+  "Other": "other",
+  "Programming Languages": "programming-languages",
+  "SCM Providers": "scm-providers",
+  "Snippets": "snippets",
+  "Testing": "testing",
+  "Themes": "themes",
+  "Visualization": "visualization"
+};
+function mapCategory(vsCodeCategory) {
+  if (vsCodeCategory === void 0) return void 0;
+  return CATEGORY_MAP[vsCodeCategory];
+}
+function mapActivationEvents(manifest) {
+  const events = manifest.activationEvents;
+  if (!events || events.length === 0) return [];
+  return events.map((event) => {
+    if (event === "onStartupFinished") return "onStartup";
+    return event;
+  });
+}
+function mapExtensionKind(manifest) {
+  const contributes = manifest.contributes;
+  if (contributes) {
+    const contributionKeys = Object.keys(contributes).filter(
+      (key) => contributes[key] !== void 0
+    );
+    const themeKeys = /* @__PURE__ */ new Set(["themes", "iconThemes", "productIconThemes", "colors"]);
+    const isThemeOnly = contributionKeys.length > 0 && contributionKeys.every((key) => themeKeys.has(key));
+    if (isThemeOnly) return "theme";
+    if (contributes.localizations && contributes.localizations.length > 0) {
+      return "pack";
+    }
+  }
+  if (manifest.extensionKind?.includes("workspace")) {
+    return "app";
+  }
+  return "ui-extension";
+}
+function vsCodeToFlowState(manifest) {
+  const displayName = typeof manifest.displayName === "string" ? manifest.displayName : manifest.displayName?.value ?? manifest.name;
+  const result = {
+    id: `${manifest.publisher}.${manifest.name}`,
+    displayName,
+    version: manifest.version,
+    publisher: manifest.publisher,
+    main: manifest.main ?? manifest.browser ?? ""
+  };
+  if (manifest.browser !== void 0) {
+    result.browser = manifest.browser;
+  }
+  const category = mapCategory(manifest.categories?.[0]);
+  if (category !== void 0) {
+    result.category = category;
+  }
+  const extensionType = mapExtensionKind(manifest);
+  if (extensionType !== "ui-extension") {
+    result.extensionType = extensionType;
+  }
+  const activationEvents = mapActivationEvents(manifest);
+  if (activationEvents.length > 0) {
+    result.activationEvents = activationEvents;
+  }
+  if (manifest.contributes !== void 0) {
+    result.contributes = manifest.contributes;
+  }
+  return result;
+}
+var REVERSE_CATEGORY_MAP = Object.fromEntries(
+  Object.entries(CATEGORY_MAP).map(([vsCode, flowstate]) => [flowstate, vsCode])
+);
+function reverseCategory(flowstateCategory) {
+  if (flowstateCategory === void 0) return void 0;
+  return REVERSE_CATEGORY_MAP[flowstateCategory];
+}
+function reverseActivationEvents(events) {
+  if (!events || events.length === 0) return [];
+  return events.map((event) => {
+    if (event === "onStartup") return "onStartupFinished";
+    return event;
+  });
+}
+function reverseExtensionKind(extensionType) {
+  switch (extensionType) {
+    case "app":
+      return ["workspace"];
+    case "theme":
+    case "pack":
+      return ["ui"];
+    default:
+      return void 0;
+  }
+}
+function flowStateToVsCode(manifest) {
+  const dotIndex = manifest.id.indexOf(".");
+  const name = dotIndex >= 0 ? manifest.id.slice(dotIndex + 1) : manifest.id;
+  const publisher = manifest.publisher ?? (dotIndex >= 0 ? manifest.id.slice(0, dotIndex) : "");
+  const result = {
+    name,
+    publisher,
+    version: manifest.version,
+    displayName: manifest.displayName
+  };
+  if (manifest.main) {
+    result.main = manifest.main;
+  }
+  if (manifest.browser !== void 0) {
+    result.browser = manifest.browser;
+  }
+  const vsCodeCategory = reverseCategory(manifest.category);
+  if (vsCodeCategory !== void 0) {
+    result.categories = [vsCodeCategory];
+  }
+  const extensionKind = reverseExtensionKind(manifest.extensionType);
+  if (extensionKind !== void 0) {
+    result.extensionKind = extensionKind;
+  }
+  const activationEvents = reverseActivationEvents(manifest.activationEvents);
+  if (activationEvents.length > 0) {
+    result.activationEvents = activationEvents;
+  }
+  if (manifest.contributes !== void 0) {
+    result.contributes = manifest.contributes;
+  }
+  return result;
+}
+var DECLARATIVE_CONTRIBUTION_POINTS = /* @__PURE__ */ new Set([
+  "themes",
+  "iconThemes",
+  "productIconThemes",
+  "colors",
+  "grammars",
+  "snippets",
+  "languages",
+  "keybindings",
+  "configuration",
+  "configurationDefaults",
+  "jsonValidation",
+  "localizations",
+  "semanticTokenTypes",
+  "semanticTokenModifiers",
+  "semanticTokenScopes"
+]);
+var VsixScanError = class _VsixScanError extends Error {
+  constructor(code, message) {
+    super(message);
+    Object.setPrototypeOf(this, _VsixScanError.prototype);
+    this.name = "VsixScanError";
+    this.code = code;
+  }
+};
+function classifyDeclarative(manifest) {
+  if (manifest.main || manifest.browser) return false;
+  const contributes = manifest.contributes;
+  if (!contributes) return true;
+  const keys = Object.keys(contributes).filter(
+    (key) => contributes[key] !== void 0
+  );
+  if (keys.length === 0) return true;
+  return keys.every((key) => DECLARATIVE_CONTRIBUTION_POINTS.has(key));
+}
+function enumerateContributionPoints(manifest) {
+  const contributes = manifest.contributes;
+  if (!contributes) return [];
+  return Object.keys(contributes).filter((key) => {
+    const value = contributes[key];
+    if (value === void 0 || value === null) return false;
+    if (Array.isArray(value) && value.length === 0) return false;
+    if (typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0)
+      return false;
+    return true;
+  }).sort();
+}
+var textDecoder = new TextDecoder();
+var VSCODE_NAMESPACE_PATTERN = /\bvscode\.(\w+)/g;
+function detectApiNamespaces(assets) {
+  const namespaces = /* @__PURE__ */ new Set();
+  for (const [path, content] of assets) {
+    if (!/\.[cm]?js$/.test(path)) continue;
+    const text = textDecoder.decode(content);
+    let match;
+    VSCODE_NAMESPACE_PATTERN.lastIndex = 0;
+    while ((match = VSCODE_NAMESPACE_PATTERN.exec(text)) !== null) {
+      namespaces.add(`vscode.${match[1]}`);
+    }
+  }
+  return Array.from(namespaces).sort();
+}
+function buildCompatibilityReport(manifest, apiNamespaces) {
+  const contributionKeys = enumerateContributionPoints(manifest);
+  const supported = contributionKeys.filter((key) => DECLARATIVE_CONTRIBUTION_POINTS.has(key));
+  const unsupported = contributionKeys.filter((key) => !DECLARATIVE_CONTRIBUTION_POINTS.has(key));
+  const warnings = [];
+  if (manifest.main || manifest.browser) {
+    warnings.push("Extension has a code entry point and requires an extension host to run.");
+  }
+  if (unsupported.length > 0) {
+    warnings.push(
+      `Unsupported contribution points: ${unsupported.join(", ")}. These require a VS Code extension host.`
+    );
+  }
+  if (apiNamespaces.length > 0) {
+    warnings.push(`Uses VS Code API namespaces: ${apiNamespaces.join(", ")}.`);
+  }
+  const hasEntryPoint = Boolean(manifest.main || manifest.browser);
+  const needsRuntime = hasEntryPoint || apiNamespaces.length > 0 || unsupported.length > 0;
+  let level;
+  if (!needsRuntime && supported.length > 0) {
+    level = "declarative-only";
+  } else if (needsRuntime && supported.length > 0) {
+    level = "partial";
+  } else {
+    level = "unsupported";
+  }
+  return {
+    level,
+    supported,
+    unsupported,
+    apiNamespacesUsed: apiNamespaces,
+    warnings
+  };
+}
+var EXTENSION_PREFIX = "extension/";
+function scanVsix(data) {
+  let entries;
+  try {
+    entries = fflate.unzipSync(data);
+  } catch {
+    throw new VsixScanError("INVALID_ZIP", "Failed to decompress VSIX archive: invalid ZIP data.");
+  }
+  const assets = /* @__PURE__ */ new Map();
+  for (const [path, content] of Object.entries(entries)) {
+    if (path.startsWith(EXTENSION_PREFIX)) {
+      const relativePath = path.slice(EXTENSION_PREFIX.length);
+      if (relativePath.length > 0) {
+        assets.set(relativePath, content);
+      }
+    }
+  }
+  const manifestData = assets.get("package.json");
+  if (!manifestData) {
+    throw new VsixScanError(
+      "MISSING_MANIFEST",
+      "VSIX archive does not contain extension/package.json."
+    );
+  }
+  let rawManifest;
+  try {
+    rawManifest = JSON.parse(textDecoder.decode(manifestData));
+  } catch {
+    throw new VsixScanError(
+      "INVALID_MANIFEST",
+      "Failed to parse extension/package.json: invalid JSON."
+    );
+  }
+  const engines = rawManifest["engines"];
+  if (typeof rawManifest["name"] !== "string" || typeof rawManifest["publisher"] !== "string" || typeof rawManifest["version"] !== "string" || typeof engines !== "object" || engines === null || typeof engines["vscode"] !== "string") {
+    throw new VsixScanError(
+      "INVALID_MANIFEST",
+      "Extension manifest missing required fields: name, publisher, version, and engines.vscode are required."
+    );
+  }
+  const vsCodeManifest = rawManifest;
+  const flowstateManifest = vsCodeToFlowState(vsCodeManifest);
+  const isDeclarative = classifyDeclarative(vsCodeManifest);
+  const contributionPoints = enumerateContributionPoints(vsCodeManifest);
+  const apiNamespaces = detectApiNamespaces(assets);
+  const compatibility = buildCompatibilityReport(vsCodeManifest, apiNamespaces);
+  return {
+    vsCodeManifest,
+    flowstateManifest,
+    isDeclarative,
+    contributionPoints,
+    assets,
+    compatibility
+  };
+}
+
+// src/compatibility-scorer.ts
+var SUPPORT_WEIGHTS = {
+  native: 1,
+  polyfill: 0.8,
+  partial: 0.5,
+  unsupported: 0
+};
+var PLATFORM_SUPPORT = {
+  desktop: {
+    themes: "native",
+    iconThemes: "native",
+    productIconThemes: "native",
+    colors: "native",
+    grammars: "native",
+    snippets: "native",
+    languages: "native",
+    keybindings: "native",
+    configuration: "native",
+    configurationDefaults: "native",
+    jsonValidation: "native",
+    localizations: "native",
+    semanticTokenTypes: "native",
+    semanticTokenModifiers: "native",
+    semanticTokenScopes: "native",
+    commands: "polyfill",
+    menus: "polyfill",
+    views: "partial",
+    viewsContainers: "partial"
+  },
+  web: {
+    themes: "native",
+    iconThemes: "native",
+    productIconThemes: "native",
+    colors: "native",
+    grammars: "native",
+    snippets: "native",
+    languages: "native",
+    keybindings: "native",
+    configuration: "native",
+    configurationDefaults: "native",
+    jsonValidation: "native",
+    localizations: "native",
+    semanticTokenTypes: "native",
+    semanticTokenModifiers: "native",
+    semanticTokenScopes: "native"
+  },
+  mobile: {
+    themes: "native",
+    colors: "native",
+    snippets: "native",
+    languages: "native",
+    keybindings: "partial",
+    configuration: "native",
+    configurationDefaults: "native",
+    localizations: "native"
+  }
+};
+var PLATFORMS_WITH_EXTENSION_HOST = /* @__PURE__ */ new Set(["desktop"]);
+var ENTRY_POINT_PENALTY = 0.5;
+function getPlatformSupport(platform) {
+  return { ...PLATFORM_SUPPORT[platform] };
+}
+function scoreExtension(manifest, platform, apiNamespaces = []) {
+  const contributionKeys = enumerateContributionPoints(manifest);
+  const platformSupport = PLATFORM_SUPPORT[platform];
+  const breakdown = contributionKeys.map((key) => {
+    const status = platformSupport[key] ?? "unsupported";
+    return {
+      key,
+      status,
+      weight: SUPPORT_WEIGHTS[status]
+    };
+  });
+  let score;
+  if (breakdown.length === 0) {
+    score = 0;
+  } else {
+    const totalWeight = breakdown.reduce((sum, point) => sum + point.weight, 0);
+    score = Math.round(totalWeight / breakdown.length * 100);
+  }
+  const hasEntryPoint = Boolean(manifest.main || manifest.browser);
+  if (hasEntryPoint && !PLATFORMS_WITH_EXTENSION_HOST.has(platform)) {
+    score = Math.round(score * ENTRY_POINT_PENALTY);
+  }
+  const level = deriveLevel(score);
+  const recommendations = generateRecommendations(breakdown, manifest, platform);
+  const report = buildCompatibilityReport(manifest, apiNamespaces);
+  return {
+    score,
+    level,
+    platform,
+    breakdown,
+    report,
+    recommendations
+  };
+}
+function generateRecommendations(breakdown, manifest, platform) {
+  const recommendations = [];
+  const hasEntryPoint = Boolean(manifest.main || manifest.browser);
+  const unsupportedPoints = breakdown.filter((p) => p.status === "unsupported");
+  const partialPoints = breakdown.filter((p) => p.status === "partial");
+  const allNative = breakdown.length > 0 && breakdown.every((p) => p.status === "native");
+  if (hasEntryPoint && !PLATFORMS_WITH_EXTENSION_HOST.has(platform)) {
+    recommendations.push(
+      "This extension requires an extension host \u2014 only declarative contributions will work on this platform."
+    );
+  }
+  if (unsupportedPoints.length > 0 && platform !== "desktop") {
+    const pointNames = unsupportedPoints.map((p) => p.key).join(", ");
+    recommendations.push(
+      `Consider using the desktop platform for full support of: ${pointNames}.`
+    );
+  }
+  if (partialPoints.length > 0) {
+    const pointNames = partialPoints.map((p) => p.key).join(", ");
+    recommendations.push(
+      `Partial support for: ${pointNames}. Some features may not work as expected.`
+    );
+  }
+  if (allNative && (!hasEntryPoint || PLATFORMS_WITH_EXTENSION_HOST.has(platform))) {
+    recommendations.push("All contribution points are natively supported on this platform.");
+  }
+  return recommendations;
+}
+function deriveLevel(score) {
+  if (score >= 90) return "full";
+  if (score >= 50) return "partial";
+  if (score > 0) return "declarative-only";
+  return "unsupported";
+}
+
+// src/dependency-resolver.ts
+function normalizeExtensionId(id) {
+  return id.toLowerCase();
+}
+function extractDependencyNode(manifest) {
+  const id = normalizeExtensionId(`${manifest.publisher}.${manifest.name}`);
+  const extensionDependencies = (manifest.extensionDependencies ?? []).map(normalizeExtensionId);
+  const extensionPack = (manifest.extensionPack ?? []).map(normalizeExtensionId);
+  return { id, extensionDependencies, extensionPack };
+}
+function buildDependencyGraph(nodes) {
+  const nodeMap = /* @__PURE__ */ new Map();
+  const edges = [];
+  const adjacency = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    nodeMap.set(node.id, node);
+    if (!adjacency.has(node.id)) {
+      adjacency.set(node.id, /* @__PURE__ */ new Set());
+    }
+  }
+  for (const node of nodes) {
+    for (const dep of node.extensionDependencies) {
+      edges.push({ from: node.id, to: dep, type: "dependency" });
+      adjacency.get(node.id).add(dep);
+      if (!nodeMap.has(dep)) {
+        nodeMap.set(dep, { id: dep, extensionDependencies: [], extensionPack: [] });
+        adjacency.set(dep, /* @__PURE__ */ new Set());
+      }
+    }
+    for (const member of node.extensionPack) {
+      edges.push({ from: node.id, to: member, type: "pack" });
+      adjacency.get(node.id).add(member);
+      if (!nodeMap.has(member)) {
+        nodeMap.set(member, { id: member, extensionDependencies: [], extensionPack: [] });
+        adjacency.set(member, /* @__PURE__ */ new Set());
+      }
+    }
+  }
+  return { nodes: nodeMap, edges, adjacency };
+}
+function resolveDependencies(nodes) {
+  const graph = buildDependencyGraph(nodes);
+  if (graph.nodes.size === 0) {
+    return { ok: true, order: [], graph };
+  }
+  const reverseAdj = /* @__PURE__ */ new Map();
+  for (const id of graph.nodes.keys()) {
+    reverseAdj.set(id, /* @__PURE__ */ new Set());
+  }
+  for (const [id, deps] of graph.adjacency) {
+    for (const dep of deps) {
+      reverseAdj.get(dep).add(id);
+    }
+  }
+  const inDegree = /* @__PURE__ */ new Map();
+  for (const [id, deps] of graph.adjacency) {
+    inDegree.set(id, deps.size);
+  }
+  const queue = [];
+  for (const [id, degree] of inDegree) {
+    if (degree === 0) {
+      queue.push(id);
+    }
+  }
+  queue.sort();
+  const order = [];
+  let queueIdx = 0;
+  while (queueIdx < queue.length) {
+    const current = queue[queueIdx++];
+    order.push(current);
+    const freed = [];
+    for (const dependent of reverseAdj.get(current)) {
+      const newDegree = inDegree.get(dependent) - 1;
+      inDegree.set(dependent, newDegree);
+      if (newDegree === 0) {
+        freed.push(dependent);
+      }
+    }
+    if (freed.length > 0) {
+      freed.sort();
+      queue.push(...freed);
+    }
+  }
+  if (order.length < graph.nodes.size) {
+    const visited = new Set(order);
+    const participants = Array.from(graph.nodes.keys()).filter((id) => !visited.has(id)).sort();
+    return { ok: false, error: "circular-dependency", participants, graph };
+  }
+  return { ok: true, order, graph };
+}
+
+// src/openvsx-client.ts
+var DEFAULT_BASE_URL = "https://open-vsx.org/api";
+var OpenVSXClient = class {
+  constructor(options) {
+    const raw = options?.baseUrl ?? DEFAULT_BASE_URL;
+    this.baseUrl = raw.endsWith("/") ? raw.slice(0, -1) : raw;
+    this.fetch = options?.fetch ?? globalThis.fetch;
+  }
+  // -------------------------------------------------------------------------
+  // Search & query
+  // -------------------------------------------------------------------------
+  /**
+   * Search extensions by text query.
+   *
+   * @param params - Search parameters (query, category, sort, pagination)
+   * @returns Paginated search results
+   */
+  async search(params) {
+    const queryParams = {};
+    if (params) {
+      if (params.query !== void 0) queryParams["query"] = params.query;
+      if (params.category !== void 0) queryParams["category"] = params.category;
+      if (params.targetPlatform !== void 0) queryParams["targetPlatform"] = params.targetPlatform;
+      if (params.size !== void 0) queryParams["size"] = String(params.size);
+      if (params.offset !== void 0) queryParams["offset"] = String(params.offset);
+      if (params.sortOrder !== void 0) queryParams["sortOrder"] = params.sortOrder;
+      if (params.sortBy !== void 0) queryParams["sortBy"] = params.sortBy;
+      if (params.includeAllVersions !== void 0)
+        queryParams["includeAllVersions"] = String(params.includeAllVersions);
+    }
+    return this._get("/-/search", queryParams);
+  }
+  /**
+   * Query extensions with structured field matching.
+   *
+   * @param params - Query parameters (namespace, extension name, ID, UUID, etc.)
+   * @returns Paginated query results with full extension metadata
+   */
+  async query(params) {
+    const queryParams = {};
+    if (params) {
+      if (params.namespaceName !== void 0) queryParams["namespaceName"] = params.namespaceName;
+      if (params.extensionName !== void 0) queryParams["extensionName"] = params.extensionName;
+      if (params.extensionVersion !== void 0)
+        queryParams["extensionVersion"] = params.extensionVersion;
+      if (params.extensionId !== void 0) queryParams["extensionId"] = params.extensionId;
+      if (params.extensionUuid !== void 0) queryParams["extensionUuid"] = params.extensionUuid;
+      if (params.namespaceUuid !== void 0) queryParams["namespaceUuid"] = params.namespaceUuid;
+      if (params.includeAllVersions !== void 0)
+        queryParams["includeAllVersions"] = String(params.includeAllVersions);
+      if (params.targetPlatform !== void 0) queryParams["targetPlatform"] = params.targetPlatform;
+      if (params.size !== void 0) queryParams["size"] = String(params.size);
+      if (params.offset !== void 0) queryParams["offset"] = String(params.offset);
+    }
+    return this._get("/-/query", queryParams);
+  }
+  // -------------------------------------------------------------------------
+  // Extension metadata
+  // -------------------------------------------------------------------------
+  /**
+   * Get extension metadata (latest version or specific version).
+   *
+   * @param namespace - Publisher namespace (e.g., `'ms-python'`)
+   * @param name - Extension name (e.g., `'python'`)
+   * @param version - Specific version string (omit for latest)
+   * @param targetPlatform - Target platform filter
+   * @returns Full extension metadata
+   */
+  async getExtension(namespace, name, version, targetPlatform) {
+    let path = `/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}`;
+    if (targetPlatform) {
+      path += `/${encodeURIComponent(targetPlatform)}`;
+    }
+    if (version) {
+      path += `/${encodeURIComponent(version)}`;
+    }
+    return this._get(path);
+  }
+  // -------------------------------------------------------------------------
+  // Namespace
+  // -------------------------------------------------------------------------
+  /**
+   * Get namespace information with extension listing.
+   *
+   * @param namespace - Namespace name (e.g., `'ms-python'`)
+   * @returns Namespace with map of extension name → API URL
+   */
+  async getNamespace(namespace) {
+    return this._get(`/${encodeURIComponent(namespace)}`);
+  }
+  /**
+   * Get namespace details including display name, social links, and extensions.
+   *
+   * @param namespace - Namespace name
+   * @returns Namespace details with social links and extension summaries
+   */
+  async getNamespaceDetails(namespace) {
+    return this._get(`/${encodeURIComponent(namespace)}/details`);
+  }
+  // -------------------------------------------------------------------------
+  // Versions
+  // -------------------------------------------------------------------------
+  /**
+   * List extension versions with pagination.
+   *
+   * @param namespace - Publisher namespace
+   * @param name - Extension name
+   * @param params - Pagination and platform filter options
+   * @returns Paginated version listing (version string → API URL)
+   */
+  async getVersions(namespace, name, params) {
+    let path = `/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}`;
+    if (params?.targetPlatform) {
+      path += `/${encodeURIComponent(params.targetPlatform)}`;
+    }
+    path += "/versions";
+    const queryParams = {};
+    if (params?.size !== void 0) queryParams["size"] = String(params.size);
+    if (params?.offset !== void 0) queryParams["offset"] = String(params.offset);
+    return this._get(path, queryParams);
+  }
+  /**
+   * List version references with engine compatibility and file URLs.
+   *
+   * @param namespace - Publisher namespace
+   * @param name - Extension name
+   * @param params - Pagination and platform filter options
+   * @returns Paginated version references
+   */
+  async getVersionReferences(namespace, name, params) {
+    let path = `/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}`;
+    if (params?.targetPlatform) {
+      path += `/${encodeURIComponent(params.targetPlatform)}`;
+    }
+    path += "/version-references";
+    const queryParams = {};
+    if (params?.size !== void 0) queryParams["size"] = String(params.size);
+    if (params?.offset !== void 0) queryParams["offset"] = String(params.offset);
+    return this._get(path, queryParams);
+  }
+  // -------------------------------------------------------------------------
+  // Reviews
+  // -------------------------------------------------------------------------
+  /**
+   * Get all reviews for an extension.
+   *
+   * @param namespace - Publisher namespace
+   * @param name - Extension name
+   * @returns Review list with all reviews (not paginated)
+   */
+  async getReviews(namespace, name) {
+    return this._get(
+      `/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}/reviews`
+    );
+  }
+  // -------------------------------------------------------------------------
+  // URL builders (pure, no fetch)
+  // -------------------------------------------------------------------------
+  /**
+   * Build a VSIX download URL for a specific extension version.
+   *
+   * This is a pure URL builder — no network request is made.
+   *
+   * @param namespace - Publisher namespace
+   * @param name - Extension name
+   * @param version - Version string
+   * @param targetPlatform - Target platform (omit for universal)
+   * @returns Full download URL
+   */
+  getDownloadUrl(namespace, name, version, targetPlatform) {
+    let path = `/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}`;
+    if (targetPlatform) {
+      path += `/${encodeURIComponent(targetPlatform)}`;
+    }
+    path += `/${encodeURIComponent(version)}/file/${encodeURIComponent(namespace)}.${encodeURIComponent(name)}-${encodeURIComponent(version)}.vsix`;
+    return `${this.baseUrl}${path}`;
+  }
+  /**
+   * Build a URL for accessing an extension file (README, icon, etc.).
+   *
+   * This is a pure URL builder — no network request is made.
+   *
+   * @param namespace - Publisher namespace
+   * @param name - Extension name
+   * @param version - Version string
+   * @param filePath - Relative file path within the extension
+   * @param targetPlatform - Target platform (omit for universal)
+   * @returns Full file URL
+   */
+  resolveFileUrl(namespace, name, version, filePath, targetPlatform) {
+    let path = `/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}`;
+    if (targetPlatform) {
+      path += `/${encodeURIComponent(targetPlatform)}`;
+    }
+    const encodedFilePath = filePath.split("/").map(encodeURIComponent).join("/");
+    path += `/${encodeURIComponent(version)}/file/${encodedFilePath}`;
+    return `${this.baseUrl}${path}`;
+  }
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+  /** Build a full URL with optional query parameters. */
+  _buildUrl(path, params) {
+    const url = `${this.baseUrl}${path}`;
+    if (!params || Object.keys(params).length === 0) {
+      return url;
+    }
+    const searchParams = new URLSearchParams(params);
+    return `${url}?${searchParams.toString()}`;
+  }
+  /** Execute a GET request and return a typed result. */
+  async _get(path, params) {
+    const url = this._buildUrl(path, params);
+    let response;
+    try {
+      response = await this.fetch(url);
+    } catch (err) {
+      return {
+        ok: false,
+        statusCode: 0,
+        error: err instanceof Error ? err.message : "Network error"
+      };
+    }
+    if (!response.ok) {
+      let errorMessage = `HTTP ${response.status}`;
+      try {
+        const body = await response.json();
+        if (typeof body["error"] === "string") {
+          errorMessage = body["error"];
+        }
+      } catch {
+      }
+      return { ok: false, statusCode: response.status, error: errorMessage };
+    }
+    let data;
+    try {
+      data = await response.json();
+    } catch {
+      return { ok: false, statusCode: response.status, error: "Invalid JSON response" };
+    }
+    return { ok: true, data };
+  }
+};
+
+// src/federation-client.ts
+var DEFAULT_CACHE_TTL_SECONDS = 3600;
+function generateCacheKey(endpoint, params = {}) {
+  const sortedEntries = Object.entries(params).sort(([a], [b]) => a.localeCompare(b));
+  const paramString = sortedEntries.map(([k, v]) => `${k}=${v}`).join("&");
+  return `${endpoint}:${paramString}`;
+}
+function matchesFilter(extension, filter, contributionPoints) {
+  if (filter.blockedPublishers && filter.blockedPublishers.length > 0 && extension.namespace) {
+    const ns = extension.namespace.toLowerCase();
+    if (filter.blockedPublishers.some((bp) => bp.toLowerCase() === ns)) {
+      return { allowed: false, reason: `Publisher '${extension.namespace}' is blocked` };
+    }
+  }
+  if (filter.allowedCategories && filter.allowedCategories.length > 0) {
+    const categories = extension.categories ?? [];
+    const allowedLower = filter.allowedCategories.map((c) => c.toLowerCase());
+    const hasAllowedCategory = categories.some((cat) => allowedLower.includes(cat.toLowerCase()));
+    if (!hasAllowedCategory) {
+      return {
+        allowed: false,
+        reason: `No matching category (has: ${categories.join(", ")}; allowed: ${filter.allowedCategories.join(", ")})`
+      };
+    }
+  }
+  if (filter.declarativeOnly && contributionPoints) {
+    if (!isDeclarativeExtension(contributionPoints)) {
+      return {
+        allowed: false,
+        reason: "Extension uses non-declarative contribution points"
+      };
+    }
+  }
+  return { allowed: true };
+}
+function isDeclarativeExtension(contributionPoints) {
+  return contributionPoints.every((cp) => DECLARATIVE_CONTRIBUTION_POINTS.has(cp));
+}
+var FederationClient = class {
+  /**
+   * Create a new federation client.
+   *
+   * @param config - Federation configuration
+   * @param upstreamClient - Optional pre-configured OpenVSXClient (created from config if not provided)
+   */
+  constructor(config, upstreamClient) {
+    this.config = config;
+    this.cacheTtl = config.cacheTtlSeconds ?? DEFAULT_CACHE_TTL_SECONDS;
+    if (config.mode === "standalone") {
+      this.upstream = null;
+    } else if (upstreamClient) {
+      this.upstream = upstreamClient;
+    } else {
+      this.upstream = new OpenVSXClient(
+        config.upstream ? { baseUrl: config.upstream } : void 0
+      );
+    }
+  }
+  /**
+   * Search extensions with filters applied.
+   *
+   * In standalone mode, returns empty results. In proxy/mirror mode,
+   * delegates to upstream and applies filters.
+   */
+  async search(params) {
+    const cacheKey = this.getCacheKey("search", params ? this._searchParamsToRecord(params) : void 0);
+    if (!this.upstream) {
+      return {
+        ok: true,
+        data: {
+          extensions: [],
+          totalSize: 0,
+          filtered: 0,
+          source: "local",
+          cacheKey
+        }
+      };
+    }
+    const result = await this.upstream.search(params);
+    if (!result.ok) {
+      return result;
+    }
+    const { extensions, totalSize } = result.data;
+    const filter = this.config.filter;
+    if (filter) {
+      const passed = [];
+      let filteredCount = 0;
+      for (const ext of extensions) {
+        const extWithCategories = ext;
+        const categories = extWithCategories.categories;
+        const check = matchesFilter(
+          categories ? { categories, namespace: ext.namespace, name: ext.name } : { namespace: ext.namespace, name: ext.name },
+          filter
+        );
+        if (check.allowed) {
+          passed.push(ext);
+        } else {
+          filteredCount++;
+        }
+      }
+      return {
+        ok: true,
+        data: {
+          extensions: passed,
+          totalSize,
+          filtered: filteredCount,
+          source: "upstream",
+          cacheKey
+        }
+      };
+    }
+    return {
+      ok: true,
+      data: {
+        extensions,
+        totalSize,
+        filtered: 0,
+        source: "upstream",
+        cacheKey
+      }
+    };
+  }
+  /**
+   * Get a single extension with filter check.
+   *
+   * In standalone mode, returns null. In proxy/mirror mode,
+   * fetches from upstream and checks against filters.
+   */
+  async getExtension(namespace, name, version) {
+    const params = { namespace, name };
+    if (version) {
+      params["version"] = version;
+    }
+    const cacheKey = this.getCacheKey("extension", params);
+    if (!this.upstream) {
+      return {
+        ok: true,
+        data: {
+          extension: null,
+          filtered: false,
+          source: "local",
+          cacheKey
+        }
+      };
+    }
+    const result = await this.upstream.getExtension(namespace, name, version);
+    if (!result.ok) {
+      return result;
+    }
+    const ext = result.data;
+    const filter = this.config.filter;
+    if (filter) {
+      const check = matchesFilter(
+        {
+          categories: ext.categories,
+          namespace: ext.namespace,
+          name: ext.name
+        },
+        filter
+      );
+      if (!check.allowed) {
+        const data = {
+          extension: null,
+          filtered: true,
+          source: "upstream",
+          cacheKey
+        };
+        if (check.reason) {
+          data.filterReason = check.reason;
+        }
+        return { ok: true, data };
+      }
+    }
+    return {
+      ok: true,
+      data: {
+        extension: ext,
+        filtered: false,
+        source: "upstream",
+        cacheKey
+      }
+    };
+  }
+  /**
+   * Get a VSIX download URL for a specific extension version.
+   *
+   * Returns null in standalone mode (no upstream available).
+   */
+  getDownloadUrl(namespace, name, version, targetPlatform) {
+    if (!this.upstream) {
+      return null;
+    }
+    return this.upstream.getDownloadUrl(namespace, name, version, targetPlatform);
+  }
+  /**
+   * Build a cache key for a given endpoint and parameters.
+   */
+  getCacheKey(endpoint, params) {
+    const raw = generateCacheKey(endpoint, params);
+    let key = `federation:${this.config.mode}:${raw}`;
+    if (this.config.filter) {
+      const f = this.config.filter;
+      const parts = [];
+      if (f.declarativeOnly) parts.push("d=1");
+      if (f.allowedCategories && f.allowedCategories.length > 0) {
+        parts.push(`ac=${[...f.allowedCategories].sort().join(",")}`);
+      }
+      if (f.blockedPublishers && f.blockedPublishers.length > 0) {
+        parts.push(`bp=${[...f.blockedPublishers].sort().join(",")}`);
+      }
+      if (parts.length > 0) {
+        key += `:f(${parts.join(";")})`;
+      }
+    }
+    return { key, ttlSeconds: this.cacheTtl };
+  }
+  /**
+   * Get a readonly copy of the current federation configuration.
+   */
+  getConfig() {
+    const copy = { ...this.config };
+    if (this.config.filter) {
+      copy.filter = { ...this.config.filter };
+      if (this.config.filter.allowedCategories) {
+        copy.filter.allowedCategories = [...this.config.filter.allowedCategories];
+      }
+      if (this.config.filter.blockedPublishers) {
+        copy.filter.blockedPublishers = [...this.config.filter.blockedPublishers];
+      }
+    }
+    return copy;
+  }
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+  /** Convert search params to a plain Record for cache key generation. */
+  _searchParamsToRecord(params) {
+    const record = {};
+    if (params.query !== void 0) record["query"] = params.query;
+    if (params.category !== void 0) record["category"] = params.category;
+    if (params.targetPlatform !== void 0) record["targetPlatform"] = params.targetPlatform;
+    if (params.size !== void 0) record["size"] = String(params.size);
+    if (params.offset !== void 0) record["offset"] = String(params.offset);
+    if (params.sortOrder !== void 0) record["sortOrder"] = params.sortOrder;
+    if (params.sortBy !== void 0) record["sortBy"] = params.sortBy;
+    if (params.includeAllVersions !== void 0)
+      record["includeAllVersions"] = String(params.includeAllVersions);
+    return record;
+  }
+};
+
+exports.DECLARATIVE_CONTRIBUTION_POINTS = DECLARATIVE_CONTRIBUTION_POINTS;
+exports.FederationClient = FederationClient;
+exports.OpenVSXClient = OpenVSXClient;
+exports.PLATFORM_SUPPORT = PLATFORM_SUPPORT;
+exports.SUPPORT_WEIGHTS = SUPPORT_WEIGHTS;
+exports.VsixScanError = VsixScanError;
+exports.buildCompatibilityReport = buildCompatibilityReport;
+exports.buildDependencyGraph = buildDependencyGraph;
+exports.classifyDeclarative = classifyDeclarative;
+exports.detectApiNamespaces = detectApiNamespaces;
+exports.enumerateContributionPoints = enumerateContributionPoints;
+exports.extractDependencyNode = extractDependencyNode;
+exports.flowStateToVsCode = flowStateToVsCode;
+exports.generateCacheKey = generateCacheKey;
+exports.generateRecommendations = generateRecommendations;
+exports.getPlatformSupport = getPlatformSupport;
+exports.isDeclarativeExtension = isDeclarativeExtension;
+exports.mapActivationEvents = mapActivationEvents;
+exports.mapCategory = mapCategory;
+exports.mapExtensionKind = mapExtensionKind;
+exports.matchesFilter = matchesFilter;
+exports.normalizeExtensionId = normalizeExtensionId;
+exports.resolveDependencies = resolveDependencies;
+exports.reverseActivationEvents = reverseActivationEvents;
+exports.reverseCategory = reverseCategory;
+exports.reverseExtensionKind = reverseExtensionKind;
+exports.scanVsix = scanVsix;
+exports.scoreExtension = scoreExtension;
+exports.vsCodeToFlowState = vsCodeToFlowState;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map