@jskit-ai/jskit-cli 0.2.26 → 0.2.28

package/src/server/cliRuntime/packageIntrospection/exportEntries.js

@@ -0,0 +1,259 @@
+import path from "node:path";
+import {
+  ensureArray,
+  ensureObject
+} from "../../shared/collectionUtils.js";
+import { fileExists } from "../ioAndMigrations.js";
+import { normalizeRelativePosixPath } from "../localPackageSupport.js";
+
+function collectPackageExportEntries(exportsField) {
+  const entries = [];
+  const normalizeExportSubpath = (subpath) => {
+    const normalized = String(subpath || ".").trim() || ".";
+    if (normalized === "." || normalized === "./") {
+      return {
+        normalized: ".",
+        segments: []
+      };
+    }
+
+    const withoutPrefix = normalized.startsWith("./") ? normalized.slice(2) : normalized;
+    const segments = withoutPrefix.split("/").map((value) => String(value || "").trim()).filter(Boolean);
+    return {
+      normalized: normalized.startsWith("./") ? normalized : `./${withoutPrefix}`,
+      segments
+    };
+  };
+
+  const resolveSubpathSortPriority = (subpath) => {
+    const normalized = normalizeExportSubpath(subpath);
+    const firstSegment = String(normalized.segments[0] || "").trim();
+    if (firstSegment === "client") {
+      return 0;
+    }
+    if (firstSegment === "server") {
+      return 1;
+    }
+    if (firstSegment === "shared") {
+      return 2;
+    }
+    if (normalized.normalized === ".") {
+      return 3;
+    }
+    return 10;
+  };
+
+  const appendEntry = (subpath, conditions, target) => {
+    const normalizedSubpath = String(subpath || ".").trim() || ".";
+    const normalizedTarget = String(target || "").trim();
+    if (!normalizedTarget) {
+      return;
+    }
+    const normalizedConditions = ensureArray(conditions).map((value) => String(value || "").trim()).filter(Boolean);
+    entries.push({
+      subpath: normalizedSubpath,
+      condition: normalizedConditions.length > 0 ? normalizedConditions.join(".") : "default",
+      target: normalizedTarget
+    });
+  };
+
+  const visit = (subpath, value, conditionStack = []) => {
+    if (typeof value === "string") {
+      appendEntry(subpath, conditionStack, value);
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        visit(subpath, item, conditionStack);
+      }
+      return;
+    }
+    if (!value || typeof value !== "object") {
+      return;
+    }
+    for (const [conditionName, nested] of Object.entries(value)) {
+      visit(subpath, nested, [...conditionStack, conditionName]);
+    }
+  };
+
+  if (typeof exportsField === "string" || Array.isArray(exportsField)) {
+    visit(".", exportsField, []);
+  } else if (exportsField && typeof exportsField === "object") {
+    const root = ensureObject(exportsField);
+    const rootKeys = Object.keys(root);
+    const hasSubpathKeys = rootKeys.some((key) => key.startsWith("."));
+    if (hasSubpathKeys) {
+      for (const [subpath, value] of Object.entries(root)) {
+        visit(subpath, value, []);
+      }
+    } else {
+      visit(".", root, []);
+    }
+  }
+
+  const deduplicated = [];
+  const seen = new Set();
+  for (const entry of entries) {
+    const key = `${entry.subpath}::${entry.condition}::${entry.target}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduplicated.push(entry);
+  }
+  return deduplicated.sort((left, right) => {
+    const leftPriority = resolveSubpathSortPriority(left.subpath);
+    const rightPriority = resolveSubpathSortPriority(right.subpath);
+    if (leftPriority !== rightPriority) {
+      return leftPriority - rightPriority;
+    }
+
+    const leftParts = normalizeExportSubpath(left.subpath);
+    const rightParts = normalizeExportSubpath(right.subpath);
+    const leftRoot = String(leftParts.segments[0] || "");
+    const rightRoot = String(rightParts.segments[0] || "");
+    const rootComparison = leftRoot.localeCompare(rightRoot);
+    if (rootComparison !== 0) {
+      return rootComparison;
+    }
+
+    const depthComparison = leftParts.segments.length - rightParts.segments.length;
+    if (depthComparison !== 0) {
+      return depthComparison;
+    }
+
+    const subpathComparison = left.subpath.localeCompare(right.subpath);
+    if (subpathComparison !== 0) {
+      return subpathComparison;
+    }
+    const conditionComparison = left.condition.localeCompare(right.condition);
+    if (conditionComparison !== 0) {
+      return conditionComparison;
+    }
+    return left.target.localeCompare(right.target);
+  });
+}
+
+async function describePackageExports({ packageRoot, packageJson }) {
+  const rootDir = String(packageRoot || "").trim();
+  if (!rootDir) {
+    return [];
+  }
+
+  const exportsField = ensureObject(packageJson).exports;
+  const entries = collectPackageExportEntries(exportsField);
+  const records = [];
+
+  for (const entry of entries) {
+    const subpath = String(entry.subpath || ".").trim() || ".";
+    const condition = String(entry.condition || "default").trim() || "default";
+    const target = String(entry.target || "").trim();
+    const isPattern = subpath.includes("*") || target.includes("*");
+    const isRelativeTarget = target.startsWith("./");
+    let targetExists = null;
+    if (isRelativeTarget && !isPattern) {
+      const absoluteTargetPath = path.resolve(rootDir, target);
+      targetExists = await fileExists(absoluteTargetPath);
+    }
+
+    let targetType = "external";
+    if (isPattern) {
+      targetType = "pattern";
+    } else if (isRelativeTarget) {
+      targetType = "file";
+    }
+
+    records.push({
+      subpath,
+      condition,
+      target,
+      targetType,
+      targetExists
+    });
+  }
+
+  return records;
+}
+
+function formatPackageSubpathImport(packageId, subpath) {
+  const normalizedPackageId = String(packageId || "").trim();
+  const normalizedSubpath = String(subpath || "").trim();
+  if (!normalizedPackageId) {
+    return normalizedSubpath;
+  }
+  if (!normalizedSubpath || normalizedSubpath === ".") {
+    return normalizedPackageId;
+  }
+  if (normalizedSubpath.startsWith("./")) {
+    return `${normalizedPackageId}/${normalizedSubpath.slice(2)}`;
+  }
+  if (normalizedSubpath.startsWith("/")) {
+    return `${normalizedPackageId}${normalizedSubpath}`;
+  }
+  return `${normalizedPackageId}/${normalizedSubpath}`;
+}
+
+function deriveCanonicalExportTargetForSubpath(subpath) {
+  const normalizedSubpath = String(subpath || "").trim();
+  if (!normalizedSubpath) {
+    return "";
+  }
+  if (normalizedSubpath === ".") {
+    return "./src/index.js";
+  }
+  if (!normalizedSubpath.startsWith("./")) {
+    return "";
+  }
+
+  const bareSubpath = normalizedSubpath.slice(2);
+  if (!bareSubpath) {
+    return "";
+  }
+  if (bareSubpath === "client" || bareSubpath === "server" || bareSubpath === "shared") {
+    return `./src/${bareSubpath}/index.js`;
+  }
+
+  const roots = ["client", "server", "shared"];
+  for (const root of roots) {
+    if (!bareSubpath.startsWith(`${root}/`)) {
+      continue;
+    }
+    const suffix = bareSubpath.slice(root.length + 1);
+    if (!suffix) {
+      return "";
+    }
+    const hasJsExtension = /\.(?:c|m)?js$/.test(suffix);
+    const normalizedSuffix = hasJsExtension ? suffix : `${suffix}.js`;
+    return `./src/${root}/${normalizedSuffix}`;
+  }
+
+  return "";
+}
+
+function shouldShowPackageExportTarget({ subpath, target, targetType }) {
+  if (String(targetType || "").trim() !== "file") {
+    return true;
+  }
+
+  const canonicalTarget = deriveCanonicalExportTargetForSubpath(subpath);
+  if (!canonicalTarget) {
+    return true;
+  }
+
+  const normalizeTarget = (value) => {
+    const raw = String(value || "").trim();
+    if (!raw) {
+      return "";
+    }
+    const withoutPrefix = raw.startsWith("./") ? raw.slice(2) : raw;
+    return `./${normalizeRelativePosixPath(withoutPrefix)}`;
+  };
+
+  return normalizeTarget(target) !== normalizeTarget(canonicalTarget);
+}
+
+export {
+  describePackageExports,
+  formatPackageSubpathImport,
+  shouldShowPackageExportTarget
+};

package/src/server/cliRuntime/packageIntrospection/exportedSymbols.js

@@ -0,0 +1,216 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  ensureArray,
+  ensureObject,
+  sortStrings
+} from "../../shared/collectionUtils.js";
+import { fileExists } from "../ioAndMigrations.js";
+import { normalizeRelativePosixPath } from "../localPackageSupport.js";
+
+function parseNamedExportSpecifiers(specifierSource) {
+  const source = String(specifierSource || "");
+  return source
+    .split(",")
+    .map((entry) => entry.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/g, "").trim())
+    .filter(Boolean)
+    .map((entry) => entry.replace(/\s+/g, " "))
+    .map((entry) => {
+      const aliasMatch = /^(.+?)\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)$/.exec(entry);
+      if (aliasMatch) {
+        return aliasMatch[2];
+      }
+      return entry;
+    })
+    .filter((entry) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(entry));
+}
+
+function parseExportedSymbolsFromSource(source) {
+  const text = String(source || "");
+  const symbols = new Set();
+  const starReExports = new Set();
+  const namedReExports = new Set();
+
+  const namespaceStarPattern = /export\s+\*\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)\s+from\s+["']([^"']+)["']\s*;?/g;
+  let match = namespaceStarPattern.exec(text);
+  while (match) {
+    symbols.add(String(match[1] || "").trim());
+    starReExports.add(String(match[2] || "").trim());
+    match = namespaceStarPattern.exec(text);
+  }
+
+  const starPattern = /export\s+\*\s+from\s+["']([^"']+)["']\s*;?/g;
+  match = starPattern.exec(text);
+  while (match) {
+    starReExports.add(String(match[1] || "").trim());
+    match = starPattern.exec(text);
+  }
+
+  const namedPattern = /export\s*\{([\s\S]*?)\}\s*(?:from\s*["']([^"']+)["'])?\s*;?/g;
+  match = namedPattern.exec(text);
+  while (match) {
+    const listSource = String(match[1] || "");
+    for (const symbol of parseNamedExportSpecifiers(listSource)) {
+      symbols.add(symbol);
+    }
+    if (match[2]) {
+      namedReExports.add(String(match[2] || "").trim());
+    }
+    match = namedPattern.exec(text);
+  }
+
+  const functionPattern = /export\s+(?:async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)\b/g;
+  match = functionPattern.exec(text);
+  while (match) {
+    symbols.add(String(match[1] || "").trim());
+    match = functionPattern.exec(text);
+  }
+
+  const classPattern = /export\s+class\s+([A-Za-z_$][A-Za-z0-9_$]*)\b/g;
+  match = classPattern.exec(text);
+  while (match) {
+    symbols.add(String(match[1] || "").trim());
+    match = classPattern.exec(text);
+  }
+
+  const variablePattern = /export\s+(?:const|let|var)\s+([\s\S]*?);/g;
+  match = variablePattern.exec(text);
+  while (match) {
+    const declaration = String(match[1] || "");
+    const names = declaration.split(",").map((entry) => String(entry || "").trim());
+    for (const name of names) {
+      const declarationMatch = /^([A-Za-z_$][A-Za-z0-9_$]*)\b/.exec(name);
+      if (declarationMatch) {
+        symbols.add(String(declarationMatch[1] || "").trim());
+      }
+    }
+    match = variablePattern.exec(text);
+  }
+
+  const hasDefaultExport = /\bexport\s+default\b/.test(text);
+  return {
+    symbols: sortStrings([...symbols]),
+    starReExports: sortStrings([...starReExports]),
+    namedReExports: sortStrings([...namedReExports]),
+    hasDefaultExport
+  };
+}
+
+function classifyExportedSymbols(symbols = []) {
+  const source = ensureArray(symbols).map((value) => String(value || "").trim()).filter(Boolean);
+  const providers = [];
+  const constants = [];
+  const functions = [];
+  const classesOrTypes = [];
+  const internals = [];
+  const others = [];
+
+  for (const symbol of source) {
+    if (/Provider$/.test(symbol)) {
+      providers.push(symbol);
+      continue;
+    }
+    if (/^__/.test(symbol)) {
+      internals.push(symbol);
+      continue;
+    }
+    if (/^[A-Z0-9_]+$/.test(symbol)) {
+      constants.push(symbol);
+      continue;
+    }
+    if (/^[a-z]/.test(symbol)) {
+      functions.push(symbol);
+      continue;
+    }
+    if (/^[A-Z]/.test(symbol)) {
+      classesOrTypes.push(symbol);
+      continue;
+    }
+    others.push(symbol);
+  }
+
+  return {
+    providers: sortStrings(providers),
+    constants: sortStrings(constants),
+    functions: sortStrings(functions),
+    classesOrTypes: sortStrings(classesOrTypes),
+    internals: sortStrings(internals),
+    others: sortStrings(others)
+  };
+}
+
+async function collectExportFileSymbolSummaries({ packageRoot, packageExports, notes }) {
+  const rootDir = String(packageRoot || "").trim();
+  if (!rootDir) {
+    return [];
+  }
+
+  const exportTargets = new Map();
+  for (const entry of ensureArray(packageExports)) {
+    const record = ensureObject(entry);
+    if (record.targetType !== "file" || record.targetExists !== true) {
+      continue;
+    }
+
+    const target = String(record.target || "").trim();
+    if (!target.startsWith("./")) {
+      continue;
+    }
+    const normalizedTarget = normalizeRelativePosixPath(target.replace(/^\.\//, ""));
+    const basename = path.posix.basename(normalizedTarget);
+    if (!/\.(?:js|mjs|cjs)$/i.test(basename)) {
+      continue;
+    }
+
+    if (!exportTargets.has(normalizedTarget)) {
+      exportTargets.set(normalizedTarget, {
+        file: normalizedTarget,
+        subpaths: new Set(),
+        conditions: new Set()
+      });
+    }
+    const bucket = exportTargets.get(normalizedTarget);
+    bucket.subpaths.add(String(record.subpath || ".").trim() || ".");
+    const condition = String(record.condition || "default").trim() || "default";
+    if (condition !== "default") {
+      bucket.conditions.add(condition);
+    }
+  }
+
+  const summaries = [];
+  for (const [relativeTargetPath, bucket] of exportTargets.entries()) {
+    const absoluteTargetPath = path.resolve(rootDir, relativeTargetPath);
+    if (!(await fileExists(absoluteTargetPath))) {
+      ensureArray(notes).push(`Export file missing: ${relativeTargetPath}`);
+      continue;
+    }
+
+    let source = "";
+    try {
+      source = await readFile(absoluteTargetPath, "utf8");
+    } catch (error) {
+      ensureArray(notes).push(
+        `Failed to read export file ${relativeTargetPath}: ${String(error?.message || error || "unknown error")}`
+      );
+      continue;
+    }
+
+    const summary = parseExportedSymbolsFromSource(source);
+    summaries.push({
+      file: normalizeRelativePosixPath(relativeTargetPath),
+      subpaths: sortStrings([...bucket.subpaths]),
+      conditions: sortStrings([...bucket.conditions]),
+      symbols: ensureArray(summary.symbols),
+      hasDefaultExport: Boolean(summary.hasDefaultExport),
+      starReExports: ensureArray(summary.starReExports),
+      namedReExports: ensureArray(summary.namedReExports)
+    });
+  }
+
+  return summaries.sort((left, right) => String(left.file || "").localeCompare(String(right.file || "")));
+}
+
+export {
+  classifyExportedSymbols,
+  collectExportFileSymbolSummaries
+};

package/src/server/cliRuntime/packageIntrospection/placementNormalization.js

@@ -0,0 +1,98 @@
+import {
+  ensureArray,
+  ensureObject
+} from "../../shared/collectionUtils.js";
+
+function normalizePlacementOutlets(value) {
+  const outlets = [];
+  const source = ensureArray(value);
+  for (const entry of source) {
+    const record = ensureObject(entry);
+    const host = String(record.host || "").trim();
+    const position = String(record.position || "").trim();
+    if (!host || !position) {
+      continue;
+    }
+
+    const surfaces = [...new Set(ensureArray(record.surfaces).map((item) => String(item || "").trim()).filter(Boolean))];
+    const description = String(record.description || "").trim();
+    const sourceLabel = String(record.source || "").trim();
+    outlets.push(
+      Object.freeze({
+        host,
+        position,
+        surfaces: Object.freeze(surfaces),
+        description,
+        source: sourceLabel
+      })
+    );
+  }
+
+  return Object.freeze(
+    [...outlets].sort((left, right) => {
+      const hostCompare = left.host.localeCompare(right.host);
+      if (hostCompare !== 0) {
+        return hostCompare;
+      }
+      return left.position.localeCompare(right.position);
+    })
+  );
+}
+
+function normalizePlacementContributions(value) {
+  const contributions = [];
+  for (const entry of ensureArray(value)) {
+    const record = ensureObject(entry);
+    const id = String(record.id || "").trim();
+    const host = String(record.host || "").trim();
+    const position = String(record.position || "").trim();
+    if (!id || !host || !position) {
+      continue;
+    }
+
+    const surfaces = [...new Set(ensureArray(record.surfaces).map((item) => String(item || "").trim()).filter(Boolean))];
+    const componentToken = String(record.componentToken || "").trim();
+    const when = String(record.when || "").trim();
+    const description = String(record.description || "").trim();
+    const source = String(record.source || "").trim();
+    const parsedOrder = Number(record.order);
+    const order = Number.isFinite(parsedOrder) ? Math.trunc(parsedOrder) : null;
+    contributions.push(
+      Object.freeze({
+        id,
+        host,
+        position,
+        surfaces: Object.freeze(surfaces),
+        order,
+        componentToken,
+        when,
+        description,
+        source
+      })
+    );
+  }
+
+  return Object.freeze(
+    [...contributions].sort((left, right) => {
+      const hostCompare = left.host.localeCompare(right.host);
+      if (hostCompare !== 0) {
+        return hostCompare;
+      }
+      const positionCompare = left.position.localeCompare(right.position);
+      if (positionCompare !== 0) {
+        return positionCompare;
+      }
+      const leftOrder = Number.isFinite(left.order) ? left.order : Number.POSITIVE_INFINITY;
+      const rightOrder = Number.isFinite(right.order) ? right.order : Number.POSITIVE_INFINITY;
+      if (leftOrder !== rightOrder) {
+        return leftOrder - rightOrder;
+      }
+      return left.id.localeCompare(right.id);
+    })
+  );
+}
+
+export {
+  normalizePlacementContributions,
+  normalizePlacementOutlets
+};