@topogram/cli 0.3.79 → 0.3.81

package/src/extractor-policy.js

@@ -0,0 +1,249 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableStringify } from "./format.js";
+import {
+  optionalStringArray,
+  optionalStringRecord,
+  packageAllowedByPolicy,
+  packageScopeFromName as sharedPackageScopeFromName
+} from "./package-adapters/index.js";
+
+export const EXTRACTOR_POLICY_FILE = "topogram.extractor-policy.json";
+
+/**
+ * @typedef {Object} ExtractorPolicy
+ * @property {string} version
+ * @property {string[]} allowedPackageScopes
+ * @property {string[]} allowedPackages
+ * @property {Record<string, string>} pinnedVersions
+ * @property {string[]} enabledPackages
+ */
+
+/**
+ * @typedef {Object} PackageExtractorBinding
+ * @property {string} packageName
+ * @property {string} version
+ */
+
+/**
+ * @typedef {Object} ExtractorPolicyInfo
+ * @property {string} path
+ * @property {ExtractorPolicy|null} policy
+ * @property {boolean} exists
+ * @property {ExtractorPolicyDiagnostic[]} diagnostics
+ */
+
+/**
+ * @typedef {Object} ExtractorPolicyDiagnostic
+ * @property {string} code
+ * @property {"error"|"warning"} severity
+ * @property {string} message
+ * @property {string|null} path
+ * @property {string|null} suggestedFix
+ * @property {string|null} step
+ * @property {string|null} [packageName]
+ * @property {string|null} [version]
+ */
+
+/**
+ * @param {Record<string, any>} input
+ * @returns {ExtractorPolicyDiagnostic}
+ */
+function extractorPolicyDiagnostic(input) {
+  return {
+    code: String(input.code || "extractor_policy_failed"),
+    severity: input.severity === "warning" ? "warning" : "error",
+    message: String(input.message || "Extractor policy check failed."),
+    path: typeof input.path === "string" ? input.path : null,
+    suggestedFix: typeof input.suggestedFix === "string" ? input.suggestedFix : null,
+    step: typeof input.step === "string" ? input.step : null,
+    packageName: typeof input.packageName === "string" ? input.packageName : null,
+    version: typeof input.version === "string" ? input.version : null
+  };
+}
+
+/**
+ * @returns {ExtractorPolicy}
+ */
+export function defaultExtractorPolicy() {
+  return {
+    version: "0.1",
+    allowedPackageScopes: [],
+    allowedPackages: [],
+    pinnedVersions: {},
+    enabledPackages: []
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} policyPath
+ * @returns {ExtractorPolicy}
+ */
+export function validateExtractorPolicy(value, policyPath) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${EXTRACTOR_POLICY_FILE} must contain a JSON object.`);
+  }
+  const raw = /** @type {Record<string, unknown>} */ (value);
+  const defaults = defaultExtractorPolicy();
+  return {
+    version: typeof raw.version === "string" && raw.version ? raw.version : defaults.version,
+    allowedPackageScopes: raw.allowedPackageScopes == null
+      ? defaults.allowedPackageScopes
+      : optionalStringArray(raw.allowedPackageScopes, "allowedPackageScopes", policyPath),
+    allowedPackages: optionalStringArray(raw.allowedPackages, "allowedPackages", policyPath),
+    pinnedVersions: optionalStringRecord(raw.pinnedVersions, policyPath, "package-or-extractor ids"),
+    enabledPackages: optionalStringArray(raw.enabledPackages, "enabledPackages", policyPath)
+  };
+}
+
+/**
+ * @param {string} packageName
+ * @returns {string|null}
+ */
+export function packageScopeFromName(packageName) {
+  return sharedPackageScopeFromName(packageName);
+}
+
+/**
+ * @param {ExtractorPolicy} policy
+ * @param {string} packageName
+ * @returns {boolean}
+ */
+export function extractorPackageAllowed(policy, packageName) {
+  return packageName.startsWith("@topogram/extractor-") || packageAllowedByPolicy(policy, packageName);
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string|null|undefined} policyPath
+ * @returns {string}
+ */
+function resolvePolicyPath(projectRoot, policyPath) {
+  if (policyPath) {
+    const resolved = path.resolve(projectRoot, policyPath);
+    if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+      return path.join(resolved, EXTRACTOR_POLICY_FILE);
+    }
+    return resolved;
+  }
+  return path.join(projectRoot, EXTRACTOR_POLICY_FILE);
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string|null|undefined} [policyPath]
+ * @returns {ExtractorPolicyInfo}
+ */
+export function loadExtractorPolicy(projectRoot, policyPath = null) {
+  const resolvedPolicyPath = resolvePolicyPath(projectRoot, policyPath);
+  if (!fs.existsSync(resolvedPolicyPath)) {
+    return {
+      path: resolvedPolicyPath,
+      policy: null,
+      exists: false,
+      diagnostics: []
+    };
+  }
+  try {
+    return {
+      path: resolvedPolicyPath,
+      policy: validateExtractorPolicy(JSON.parse(fs.readFileSync(resolvedPolicyPath, "utf8")), resolvedPolicyPath),
+      exists: true,
+      diagnostics: []
+    };
+  } catch (error) {
+    return {
+      path: resolvedPolicyPath,
+      policy: null,
+      exists: true,
+      diagnostics: [extractorPolicyDiagnostic({
+        code: "extractor_policy_invalid",
+        message: error instanceof Error ? error.message : String(error),
+        path: resolvedPolicyPath,
+        suggestedFix: `Fix ${EXTRACTOR_POLICY_FILE} or regenerate it with \`topogram extractor policy init\`.`,
+        step: "extractor-policy"
+      })]
+    };
+  }
+}
+
+/**
+ * @param {ExtractorPolicyInfo} policyInfo
+ * @returns {ExtractorPolicy}
+ */
+export function effectiveExtractorPolicy(policyInfo) {
+  return policyInfo.policy || defaultExtractorPolicy();
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {ExtractorPolicy} policy
+ * @param {string|null|undefined} [policyPath]
+ * @returns {ExtractorPolicy}
+ */
+export function writeExtractorPolicy(projectRoot, policy, policyPath = null) {
+  const resolvedPolicyPath = resolvePolicyPath(projectRoot, policyPath);
+  fs.writeFileSync(resolvedPolicyPath, `${stableStringify(policy)}\n`, "utf8");
+  return policy;
+}
+
+/**
+ * @param {ExtractorPolicyInfo} policyInfo
+ * @param {PackageExtractorBinding[]} bindings
+ * @param {string} [step]
+ * @returns {ExtractorPolicyDiagnostic[]}
+ */
+export function extractorPolicyDiagnosticsForPackages(policyInfo, bindings, step = "extractor-policy") {
+  if (policyInfo.diagnostics.length > 0) {
+    return policyInfo.diagnostics;
+  }
+  const policy = effectiveExtractorPolicy(policyInfo);
+  /** @type {ExtractorPolicyDiagnostic[]} */
+  const diagnostics = [];
+  for (const binding of bindings) {
+    if (!extractorPackageAllowed(policy, binding.packageName)) {
+      const scope = packageScopeFromName(binding.packageName);
+      diagnostics.push(extractorPolicyDiagnostic({
+        code: "extractor_package_denied",
+        message: `Extractor package '${binding.packageName}' is not allowed by ${EXTRACTOR_POLICY_FILE}.`,
+        path: policyInfo.path,
+        suggestedFix: `Review '${binding.packageName}', then run \`topogram extractor policy pin ${binding.packageName}@${binding.version}\` or add '${scope || binding.packageName}' to ${EXTRACTOR_POLICY_FILE}.`,
+        step,
+        packageName: binding.packageName,
+        version: binding.version
+      }));
+    }
+    const pinnedVersion = policy.pinnedVersions[binding.packageName] || null;
+    if (pinnedVersion && pinnedVersion !== binding.version) {
+      diagnostics.push(extractorPolicyDiagnostic({
+        code: "extractor_version_mismatch",
+        message: `Extractor package '${binding.packageName}' uses version '${binding.version}', but ${EXTRACTOR_POLICY_FILE} pins it to '${pinnedVersion}'.`,
+        path: policyInfo.path,
+        suggestedFix: `Use extractor version '${pinnedVersion}', or run \`topogram extractor policy pin ${binding.packageName}@${binding.version}\` after review.`,
+        step,
+        packageName: binding.packageName,
+        version: binding.version
+      }));
+    }
+  }
+  return diagnostics;
+}
+
+/**
+ * @param {string} spec
+ * @returns {{ packageName: string, version: string }}
+ */
+export function parseExtractorPolicyPin(spec) {
+  const separator = spec.lastIndexOf("@");
+  if (separator <= 0 || separator === spec.length - 1) {
+    throw new Error("Extractor policy pin requires a package name and extractor version, for example @topogram/extractor-node-cli@1.");
+  }
+  return {
+    packageName: spec.slice(0, separator),
+    version: spec.slice(separator + 1)
+  };
+}

package/src/generator/check.js

@@ -2,12 +2,18 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { createRequire } from "node:module";
 
 import {
   loadPackageGeneratorManifest,
   validateGeneratorManifest
 } from "./registry.js";
+import {
+  isPathSpec,
+  loadInstalledPackageAdapter,
+  loadLocalPackageAdapter,
+  packageNameFromSpec,
+  validateRelativeStringFileMap
+} from "../package-adapters/index.js";
 
 /**
  * @typedef {import("./registry.js").GeneratorManifest} GeneratorManifest
@@ -28,82 +34,6 @@ import {
  * @property {boolean} executesPackageCode
  */
 
-/**
- * @param {string} spec
- * @param {string} cwd
- * @returns {boolean}
- */
-function isPathSpec(spec, cwd) {
-  return spec.startsWith(".") || spec.startsWith("/") || fs.existsSync(path.resolve(cwd, spec));
-}
-
-/**
- * @param {string} spec
- * @returns {string}
- */
-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 {any} moduleValue
- * @param {string|null|undefined} exportName
- * @returns {any}
- */
-function selectPackageExport(moduleValue, exportName) {
-  if (exportName) {
-    return moduleValue?.[exportName] || moduleValue?.default?.[exportName] || null;
-  }
-  return moduleValue?.default || moduleValue;
-}
-
-/**
- * @param {string} root
- * @param {GeneratorManifest} manifest
- * @returns {{ adapter: any|null, error: string|null }}
- */
-function loadLocalAdapter(root, manifest) {
-  try {
-    const packageJsonPath = path.join(root, "package.json");
-    const requireFromPackage = createRequire(packageJsonPath);
-    return {
-      adapter: selectPackageExport(requireFromPackage(root), manifest.export),
-      error: null
-    };
-  } catch (error) {
-    return {
-      adapter: null,
-      error: `Generator package export could not be loaded from '${root}': ${error instanceof Error ? error.message : String(error)}`
-    };
-  }
-}
-
-/**
- * @param {string} packageName
- * @param {string} rootDir
- * @param {GeneratorManifest} manifest
- * @returns {{ adapter: any|null, error: string|null }}
- */
-function loadInstalledAdapter(packageName, rootDir, manifest) {
-  try {
-    const requireFromRoot = createRequire(path.join(rootDir, "package.json"));
-    return {
-      adapter: selectPackageExport(requireFromRoot(packageName), manifest.export),
-      error: null
-    };
-  } catch (error) {
-    return {
-      adapter: null,
-      error: `Generator package '${packageName}' export could not be loaded from '${rootDir}': ${error instanceof Error ? error.message : String(error)}`
-    };
-  }
-}
-
 /**
  * @param {GeneratorManifest} manifest
  * @returns {Record<string, any>}
@@ -208,14 +138,12 @@ function validateSmokeResult(result) {
   if (!result.files || typeof result.files !== "object" || Array.isArray(result.files)) {
     return { ok: false, message: "generate(context) result must include a files object", smoke: null };
   }
-  for (const [filePath, content] of Object.entries(result.files)) {
-    const normalizedPath = typeof filePath === "string" ? path.normalize(filePath) : "";
-    if (typeof filePath !== "string" || filePath.length === 0 || path.isAbsolute(filePath) || normalizedPath === ".." || normalizedPath.startsWith(`..${path.sep}`)) {
-      return { ok: false, message: "generated file paths must be non-empty relative paths", smoke: null };
-    }
-    if (typeof content !== "string") {
-      return { ok: false, message: `generated file '${filePath}' content must be a string`, smoke: null };
-    }
+  const fileMapValidation = validateRelativeStringFileMap(result.files, {
+    filePathMessage: "generated file paths must be non-empty relative paths",
+    contentMessage: (filePath) => `generated file '${filePath}' content must be a string`
+  });
+  if (!fileMapValidation.ok) {
+    return { ok: false, message: fileMapValidation.message, smoke: null };
   }
   return {
     ok: true,
@@ -304,7 +232,11 @@ export function checkGeneratorPack(sourceSpec, options = {}) {
   }
 
   if (payload.source === "path") {
-    const loaded = loadLocalAdapter(payload.packageRoot || cwd, payload.manifest);
+    const loaded = loadLocalPackageAdapter({
+      packageRoot: payload.packageRoot || cwd,
+      exportName: payload.manifest.export,
+      packageLabel: "Generator package"
+    });
     adapter = loaded.adapter;
     if (loaded.error) {
       payload.errors.push(loaded.error);
@@ -312,7 +244,12 @@ export function checkGeneratorPack(sourceSpec, options = {}) {
       return payload;
     }
   } else if (payload.packageName) {
-    const loaded = loadInstalledAdapter(payload.packageName, cwd, payload.manifest);
+    const loaded = loadInstalledPackageAdapter({
+      packageName: payload.packageName,
+      rootDir: cwd,
+      exportName: payload.manifest.export,
+      packageLabel: "Generator package"
+    });
     adapter = loaded.adapter;
     if (loaded.error) {
       payload.errors.push(loaded.error);

package/src/generator/registry/index.js

@@ -1,8 +1,11 @@
 // @ts-check
 
-import fs from "node:fs";
-import path from "node:path";
-import { createRequire } from "node:module";
+import {
+  loadPackageManifest,
+  packageInstallCommand,
+  packageInstallHint,
+  resolvePackageManifestPath
+} from "../../package-adapters/index.js";
 import { UI_GENERATOR_RENDERED_COMPONENT_PATTERNS } from "../../ui/taxonomy.js";
 
 /**
@@ -208,20 +211,12 @@ export function getGeneratorManifest(generatorId) {
   return GENERATOR_BY_ID.get(generatorId) || null;
 }
 
-/**
- * @param {string|null|undefined} rootDir
- * @returns {string}
- */
-function packageResolutionBase(rootDir) {
-  return path.join(rootDir || process.cwd(), "package.json");
-}
-
 /**
  * @param {string|null|undefined} packageName
  * @returns {string|null}
  */
 export function packageGeneratorInstallCommand(packageName) {
-  return packageName ? `npm install -D ${packageName}` : null;
+  return packageInstallCommand(packageName);
 }
 
 /**
@@ -229,8 +224,7 @@ export function packageGeneratorInstallCommand(packageName) {
  * @returns {string|null}
  */
 export function packageGeneratorInstallHint(packageName) {
-  const command = packageGeneratorInstallCommand(packageName);
-  return command ? `Install it from the project root with: ${command}` : null;
+  return packageInstallHint(packageName);
 }
 
 /**
@@ -239,41 +233,7 @@ export function packageGeneratorInstallHint(packageName) {
  * @returns {{ manifestPath: string|null, packageRoot: string|null, error: string|null }}
  */
 export function resolvePackageGeneratorManifestPath(packageName, rootDir = process.cwd()) {
-  const requireFromRoot = createRequire(packageResolutionBase(rootDir));
-  try {
-    const manifestPath = requireFromRoot.resolve(`${packageName}/topogram-generator.json`);
-    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, "topogram-generator.json");
-      if (!fs.existsSync(manifestPath)) {
-        return {
-          manifestPath: null,
-          packageRoot,
-          error: `Generator package '${packageName}' is missing topogram-generator.json`
-        };
-      }
-      return {
-        manifestPath,
-        packageRoot,
-        error: null
-      };
-    } catch {
-      const detail = manifestError instanceof Error ? manifestError.message : String(manifestError);
-      const installHint = packageGeneratorInstallHint(packageName);
-      return {
-        manifestPath: null,
-        packageRoot: null,
-        error: `Generator package '${packageName}' could not be resolved from '${rootDir || process.cwd()}': ${detail}${installHint ? `. ${installHint}` : ""}`
-      };
-    }
-  }
+  return resolvePackageManifestPath(packageName, "topogram-generator.json", rootDir, "Generator package");
 }
 
 /**
@@ -282,32 +242,13 @@ export function resolvePackageGeneratorManifestPath(packageName, rootDir = proce
  * @returns {{ manifest: GeneratorManifest|null, errors: string[], manifestPath: string|null, packageRoot: string|null }}
  */
 export function loadPackageGeneratorManifest(packageName, rootDir = process.cwd()) {
-  const resolved = resolvePackageGeneratorManifestPath(packageName, rootDir);
-  if (!resolved.manifestPath) {
-    return {
-      manifest: null,
-      errors: [resolved.error || `Generator package '${packageName}' could not be resolved`],
-      manifestPath: null,
-      packageRoot: resolved.packageRoot
-    };
-  }
-  try {
-    const manifest = JSON.parse(fs.readFileSync(resolved.manifestPath, "utf8"));
-    const validation = validateGeneratorManifest(manifest);
-    return {
-      manifest: validation.ok ? manifest : null,
-      errors: validation.errors,
-      manifestPath: resolved.manifestPath,
-      packageRoot: resolved.packageRoot
-    };
-  } catch (error) {
-    return {
-      manifest: null,
-      errors: [`Generator package '${packageName}' manifest could not be read: ${error instanceof Error ? error.message : String(error)}`],
-      manifestPath: resolved.manifestPath,
-      packageRoot: resolved.packageRoot
-    };
-  }
+  return loadPackageManifest({
+    packageName,
+    rootDir,
+    manifestFile: "topogram-generator.json",
+    packageLabel: "Generator package",
+    validateManifest: validateGeneratorManifest
+  });
 }
 
 /**

package/src/generator-policy.js

@@ -4,6 +4,12 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { stableStringify } from "./format.js";
+import {
+  optionalStringArray,
+  optionalStringRecord,
+  packageAllowedByPolicy,
+  packageScopeFromName as sharedPackageScopeFromName
+} from "./package-adapters/index.js";
 
 export const GENERATOR_POLICY_FILE = "topogram.generator-policy.json";
 
@@ -66,47 +72,6 @@ function generatorPolicyDiagnostic(input) {
   };
 }
 
-/**
- * @param {unknown} value
- * @param {string} fieldName
- * @param {string} policyPath
- * @returns {string[]}
- */
-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
- * @returns {Record<string, string>}
- */
-function optionalStringRecord(value, policyPath) {
-  if (value == null) {
-    return {};
-  }
-  if (typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`${policyPath} pinnedVersions must be an object of package-or-generator ids 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];
-  }));
-}
-
 /**
  * @returns {GeneratorPolicy}
  */
@@ -136,7 +101,7 @@ export function validateGeneratorPolicy(value, policyPath) {
       ? defaults.allowedPackageScopes
       : optionalStringArray(raw.allowedPackageScopes, "allowedPackageScopes", policyPath),
     allowedPackages: optionalStringArray(raw.allowedPackages, "allowedPackages", policyPath),
-    pinnedVersions: optionalStringRecord(raw.pinnedVersions, policyPath)
+    pinnedVersions: optionalStringRecord(raw.pinnedVersions, policyPath, "package-or-generator ids")
   };
 }
 
@@ -145,16 +110,7 @@ export function validateGeneratorPolicy(value, policyPath) {
  * @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}/*`));
+  return sharedPackageScopeFromName(packageName);
 }
 
 /**
@@ -163,11 +119,7 @@ function packageScopeMatches(allowed, scope) {
  * @returns {boolean}
  */
 export function generatorPackageAllowed(policy, packageName) {
-  if (policy.allowedPackages.includes(packageName)) {
-    return true;
-  }
-  const scope = packageScopeFromName(packageName);
-  return policy.allowedPackageScopes.some((allowed) => packageScopeMatches(allowed, scope));
+  return packageAllowedByPolicy(policy, packageName);
 }
 
 /**

package/src/import/core/registry.d.ts

@@ -1,4 +1,7 @@
 export const extractorRegistry: Record<string, any[]>;
 export const enricherRegistry: Record<string, any[]>;
+export const BUILTIN_EXTRACTOR_PACKS: any[];
 export function getExtractorsForTrack(...args: any[]): any[];
 export function getEnrichersForTrack(...args: any[]): any[];
+export function getBundledExtractorPack(...args: any[]): any;
+export function getBundledExtractorById(...args: any[]): any;