@topogram/cli 0.3.79 → 0.3.80

package/src/extractor/registry.js

@@ -0,0 +1,196 @@
+// @ts-check
+
+import {
+  loadPackageManifest,
+  packageInstallCommand,
+  packageInstallHint,
+  resolvePackageManifestPath
+} from "../package-adapters/index.js";
+import { BUILTIN_EXTRACTOR_PACKS } from "../import/core/registry.js";
+
+export const EXTRACTOR_TRACKS = ["db", "api", "ui", "cli", "workflows", "verification"];
+
+/**
+ * @typedef {Object} ExtractorManifest
+ * @property {string} id
+ * @property {string} version
+ * @property {string[]} tracks
+ * @property {"bundled"|"package"} source
+ * @property {string[]} extractors
+ * @property {Record<string, string>} stack
+ * @property {Record<string, boolean>} capabilities
+ * @property {string[]} candidateKinds
+ * @property {string[]} evidenceTypes
+ * @property {string} [package]
+ * @property {string} [export]
+ */
+
+/**
+ * @typedef {Object} ExtractorBinding
+ * @property {string} id
+ * @property {string} track
+ * @property {string} packageName
+ * @property {string} version
+ */
+
+/**
+ * @typedef {Object} ResolvedExtractorManifest
+ * @property {ExtractorManifest|null} manifest
+ * @property {string[]} errors
+ * @property {"bundled"|"package"|null} source
+ * @property {string|null} manifestPath
+ * @property {string|null} packageRoot
+ */
+
+/** @type {ExtractorManifest[]} */
+export const EXTRACTOR_MANIFESTS = BUILTIN_EXTRACTOR_PACKS.map((pack) => pack.manifest);
+
+const EXTRACTOR_MANIFEST_BY_ID = new Map(EXTRACTOR_MANIFESTS.map((manifest) => [manifest.id, manifest]));
+
+/**
+ * @param {any} value
+ * @param {boolean} [nonEmpty]
+ * @returns {boolean}
+ */
+function isStringArray(value, nonEmpty = false) {
+  return Array.isArray(value) &&
+    (!nonEmpty || value.length > 0) &&
+    value.every((entry) => typeof entry === "string" && entry.length > 0);
+}
+
+/**
+ * @param {any} value
+ * @returns {value is Record<string, string>}
+ */
+function isStringRecord(value) {
+  return Boolean(value) &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.values(value).every((entry) => typeof entry === "string");
+}
+
+/**
+ * @param {any} value
+ * @returns {value is Record<string, boolean>}
+ */
+function isBooleanRecord(value) {
+  return Boolean(value) &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.values(value).every((entry) => typeof entry === "boolean");
+}
+
+/**
+ * @param {any} manifest
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateExtractorManifest(manifest) {
+  const errors = [];
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return { ok: false, errors: ["Extractor manifest must be an object."] };
+  }
+  if (typeof manifest.id !== "string" || manifest.id.length === 0) {
+    errors.push("Extractor manifest id must be a non-empty string.");
+  }
+  if (typeof manifest.version !== "string" || manifest.version.length === 0) {
+    errors.push("Extractor manifest version must be a non-empty string.");
+  }
+  if (!isStringArray(manifest.tracks, true)) {
+    errors.push("Extractor manifest tracks must be a non-empty array of strings.");
+  } else {
+    for (const track of manifest.tracks) {
+      if (!EXTRACTOR_TRACKS.includes(track)) {
+        errors.push(`Extractor manifest track '${track}' is not supported.`);
+      }
+    }
+  }
+  if (manifest.source !== "bundled" && manifest.source !== "package") {
+    errors.push("Extractor manifest source must be 'bundled' or 'package'.");
+  }
+  if (!isStringArray(manifest.extractors, true)) {
+    errors.push("Extractor manifest extractors must be a non-empty array of strings.");
+  }
+  if (!isStringRecord(manifest.stack)) {
+    errors.push("Extractor manifest stack must be an object of string values.");
+  }
+  if (!isBooleanRecord(manifest.capabilities)) {
+    errors.push("Extractor manifest capabilities must be an object of boolean values.");
+  }
+  if (!isStringArray(manifest.candidateKinds)) {
+    errors.push("Extractor manifest candidateKinds must be an array of strings.");
+  }
+  if (!isStringArray(manifest.evidenceTypes)) {
+    errors.push("Extractor manifest evidenceTypes must be an array of strings.");
+  }
+  if (manifest.package != null && (typeof manifest.package !== "string" || manifest.package.length === 0)) {
+    errors.push("Extractor manifest package must be a non-empty string when present.");
+  }
+  if (manifest.export != null && (typeof manifest.export !== "string" || manifest.export.length === 0)) {
+    errors.push("Extractor manifest export must be a non-empty string when present.");
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * @param {string} extractorId
+ * @returns {ExtractorManifest|null}
+ */
+export function getExtractorManifest(extractorId) {
+  return EXTRACTOR_MANIFEST_BY_ID.get(extractorId) || null;
+}
+
+/**
+ * @param {string|null|undefined} packageName
+ * @returns {string|null}
+ */
+export function packageExtractorInstallCommand(packageName) {
+  return packageInstallCommand(packageName);
+}
+
+/**
+ * @param {string|null|undefined} packageName
+ * @returns {string|null}
+ */
+export function packageExtractorInstallHint(packageName) {
+  return packageInstallHint(packageName);
+}
+
+/**
+ * @param {string} packageName
+ * @param {string|null|undefined} rootDir
+ * @returns {{ manifestPath: string|null, packageRoot: string|null, error: string|null }}
+ */
+export function resolvePackageExtractorManifestPath(packageName, rootDir = process.cwd()) {
+  return resolvePackageManifestPath(packageName, "topogram-extractor.json", rootDir, "Extractor package");
+}
+
+/**
+ * @param {string} packageName
+ * @param {string|null|undefined} rootDir
+ * @returns {{ manifest: ExtractorManifest|null, errors: string[], manifestPath: string|null, packageRoot: string|null }}
+ */
+export function loadPackageExtractorManifest(packageName, rootDir = process.cwd()) {
+  return loadPackageManifest({
+    packageName,
+    rootDir,
+    manifestFile: "topogram-extractor.json",
+    packageLabel: "Extractor package",
+    validateManifest: validateExtractorManifest
+  });
+}
+
+/**
+ * @param {Record<string, any>|null|undefined} manifest
+ * @returns {ExtractorBinding[]}
+ */
+export function extractorBindingsForManifest(manifest) {
+  if (!manifest || manifest.source !== "package" || typeof manifest.package !== "string") {
+    return [];
+  }
+  return (manifest.extractors || []).map((/** @type {any} */ extractorId) => ({
+    id: String(extractorId),
+    track: Array.isArray(manifest.tracks) && manifest.tracks.length === 1 ? String(manifest.tracks[0]) : "multiple",
+    packageName: String(manifest.package),
+    version: String(manifest.version || "unknown")
+  }));
+}

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);