@topogram/cli 0.3.79 → 0.3.80

package/src/package-adapters/manifest.js

@@ -0,0 +1,108 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+import { packageInstallHint, packageResolutionBase } from "./spec.js";
+
+/**
+ * @typedef {Object} PackageManifestResolution
+ * @property {string|null} manifestPath
+ * @property {string|null} packageRoot
+ * @property {string|null} error
+ */
+
+/**
+ * @typedef {{ ok: boolean, errors: string[] }} ManifestValidation
+ */
+
+/**
+ * @param {string} packageName
+ * @param {string} manifestFile
+ * @param {string|null|undefined} rootDir
+ * @param {string} packageLabel
+ * @returns {PackageManifestResolution}
+ */
+export function resolvePackageManifestPath(packageName, manifestFile, rootDir = process.cwd(), packageLabel = "Package") {
+  const requireFromRoot = createRequire(packageResolutionBase(rootDir));
+  try {
+    const manifestPath = requireFromRoot.resolve(`${packageName}/${manifestFile}`);
+    return {
+      manifestPath,
+      packageRoot: path.dirname(manifestPath),
+      error: null
+    };
+  } catch (manifestError) {
+    try {
+      const packageJsonPath = requireFromRoot.resolve(`${packageName}/package.json`);
+      const packageRoot = path.dirname(packageJsonPath);
+      const manifestPath = path.join(packageRoot, manifestFile);
+      if (!fs.existsSync(manifestPath)) {
+        return {
+          manifestPath: null,
+          packageRoot,
+          error: `${packageLabel} '${packageName}' is missing ${manifestFile}`
+        };
+      }
+      return {
+        manifestPath,
+        packageRoot,
+        error: null
+      };
+    } catch {
+      const detail = manifestError instanceof Error ? manifestError.message : String(manifestError);
+      const installHint = packageInstallHint(packageName);
+      return {
+        manifestPath: null,
+        packageRoot: null,
+        error: `${packageLabel} '${packageName}' could not be resolved from '${rootDir || process.cwd()}': ${detail}${installHint ? `. ${installHint}` : ""}`
+      };
+    }
+  }
+}
+
+/**
+ * @template T
+ * @param {{
+ *   packageName: string,
+ *   rootDir?: string|null,
+ *   manifestFile: string,
+ *   packageLabel: string,
+ *   validateManifest: (manifest: any) => ManifestValidation
+ * }} options
+ * @returns {{ manifest: T|null, errors: string[], manifestPath: string|null, packageRoot: string|null }}
+ */
+export function loadPackageManifest(options) {
+  const resolved = resolvePackageManifestPath(
+    options.packageName,
+    options.manifestFile,
+    options.rootDir || process.cwd(),
+    options.packageLabel
+  );
+  if (!resolved.manifestPath) {
+    return {
+      manifest: null,
+      errors: [resolved.error || `${options.packageLabel} '${options.packageName}' could not be resolved`],
+      manifestPath: null,
+      packageRoot: resolved.packageRoot
+    };
+  }
+  try {
+    const manifest = JSON.parse(fs.readFileSync(resolved.manifestPath, "utf8"));
+    const validation = options.validateManifest(manifest);
+    return {
+      manifest: validation.ok ? /** @type {T} */ (manifest) : null,
+      errors: validation.errors,
+      manifestPath: resolved.manifestPath,
+      packageRoot: resolved.packageRoot
+    };
+  } catch (error) {
+    return {
+      manifest: null,
+      errors: [`${options.packageLabel} '${options.packageName}' manifest could not be read: ${error instanceof Error ? error.message : String(error)}`],
+      manifestPath: resolved.manifestPath,
+      packageRoot: resolved.packageRoot
+    };
+  }
+}

package/src/package-adapters/policy.js

@@ -0,0 +1,81 @@
+// @ts-check
+
+/**
+ * @typedef {Object} PackagePolicy
+ * @property {string} version
+ * @property {string[]} allowedPackageScopes
+ * @property {string[]} allowedPackages
+ * @property {Record<string, string>} pinnedVersions
+ */
+
+/**
+ * @param {unknown} value
+ * @param {string} fieldName
+ * @param {string} policyPath
+ * @returns {string[]}
+ */
+export function optionalStringArray(value, fieldName, policyPath) {
+  if (value == null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${policyPath} ${fieldName} must be an array of strings.`);
+  }
+  return value.map((item) => {
+    if (typeof item !== "string" || item.length === 0) {
+      throw new Error(`${policyPath} ${fieldName} must contain only non-empty strings.`);
+    }
+    return item;
+  });
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} policyPath
+ * @param {string} [pinnedLabel]
+ * @returns {Record<string, string>}
+ */
+export function optionalStringRecord(value, policyPath, pinnedLabel = "package ids") {
+  if (value == null) {
+    return {};
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${policyPath} pinnedVersions must be an object of ${pinnedLabel} to versions.`);
+  }
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => {
+    if (typeof item !== "string" || item.length === 0) {
+      throw new Error(`${policyPath} pinnedVersions['${key}'] must be a non-empty string.`);
+    }
+    return [key, item];
+  }));
+}
+
+/**
+ * @param {string} packageName
+ * @returns {string|null}
+ */
+export function packageScopeFromName(packageName) {
+  return packageName.startsWith("@") ? packageName.split("/")[0] || null : null;
+}
+
+/**
+ * @param {string} allowed
+ * @param {string|null} scope
+ * @returns {boolean}
+ */
+function packageScopeMatches(allowed, scope) {
+  return Boolean(scope && (allowed === scope || allowed === `${scope}/*`));
+}
+
+/**
+ * @param {PackagePolicy} policy
+ * @param {string} packageName
+ * @returns {boolean}
+ */
+export function packageAllowedByPolicy(policy, packageName) {
+  if (policy.allowedPackages.includes(packageName)) {
+    return true;
+  }
+  const scope = packageScopeFromName(packageName);
+  return policy.allowedPackageScopes.some((allowed) => packageScopeMatches(allowed, scope));
+}

package/src/package-adapters/spec.js

@@ -0,0 +1,51 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @param {string} spec
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function isPathSpec(spec, cwd) {
+  return spec.startsWith(".") || spec.startsWith("/") || fs.existsSync(path.resolve(cwd, spec));
+}
+
+/**
+ * @param {string} spec
+ * @returns {string}
+ */
+export function packageNameFromSpec(spec) {
+  if (spec.startsWith("@")) {
+    const versionIndex = spec.indexOf("@", 1);
+    return versionIndex > 0 ? spec.slice(0, versionIndex) : spec;
+  }
+  const versionIndex = spec.indexOf("@");
+  return versionIndex > 0 ? spec.slice(0, versionIndex) : spec;
+}
+
+/**
+ * @param {string|null|undefined} rootDir
+ * @returns {string}
+ */
+export function packageResolutionBase(rootDir) {
+  return path.join(rootDir || process.cwd(), "package.json");
+}
+
+/**
+ * @param {string|null|undefined} packageName
+ * @returns {string|null}
+ */
+export function packageInstallCommand(packageName) {
+  return packageName ? `npm install -D ${packageName}` : null;
+}
+
+/**
+ * @param {string|null|undefined} packageName
+ * @returns {string|null}
+ */
+export function packageInstallHint(packageName) {
+  const command = packageInstallCommand(packageName);
+  return command ? `Install it from the project root with: ${command}` : null;
+}