@kb-labs/policy-core 0.5.0

package/dist/index.js

@@ -0,0 +1,652 @@
+import fs from 'fs';
+import path4 from 'path';
+import { spawnSync } from 'child_process';
+import semver from 'semver';
+import { combinePermissions, defineCommandFlags } from '@kb-labs/sdk';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/core/category-resolver.ts
+var category_resolver_exports = {};
+__export(category_resolver_exports, {
+  detectCategories: () => detectCategories,
+  detectCategory: () => detectCategory
+});
+function matchesPattern(repoPath, pattern) {
+  const normalizedPath = repoPath.replace(/\/$/, "");
+  const normalizedPattern = pattern.replace(/\/$/, "");
+  if (normalizedPattern === normalizedPath) {
+    return true;
+  }
+  if (normalizedPattern.endsWith("/*")) {
+    const prefix = normalizedPattern.slice(0, -2);
+    const pathPrefix = normalizedPath.split("/").slice(0, prefix.split("/").length).join("/");
+    return pathPrefix === prefix;
+  }
+  if (normalizedPattern.includes("*")) {
+    const regexStr = normalizedPattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]+");
+    return new RegExp(`^${regexStr}$`).test(normalizedPath);
+  }
+  return false;
+}
+function detectCategory(repoPath, config) {
+  for (const [categoryName, categoryConfig] of Object.entries(config.categories)) {
+    for (const pattern of categoryConfig.paths) {
+      if (matchesPattern(repoPath, pattern)) {
+        return {
+          path: repoPath,
+          category: categoryName,
+          rules: categoryConfig.rules
+        };
+      }
+    }
+  }
+  return {
+    path: repoPath,
+    category: null,
+    rules: ["boundary-check"]
+    // default fallback rule
+  };
+}
+function detectCategories(repoPaths, config) {
+  return repoPaths.map((p) => detectCategory(p, config));
+}
+var init_category_resolver = __esm({
+  "src/core/category-resolver.ts"() {
+  }
+});
+
+// src/core/index.ts
+init_category_resolver();
+
+// src/core/workspace-scanner.ts
+init_category_resolver();
+function buildPackageMap(workspaceRoot, config) {
+  const packages = scanAllPackages(workspaceRoot, config);
+  const map = /* @__PURE__ */ new Map();
+  for (const pkg of packages) {
+    map.set(pkg.name, pkg.category);
+  }
+  return map;
+}
+function getRepoPackageNames(workspaceRoot, repoPath) {
+  const absRepoPath = path4.resolve(workspaceRoot, repoPath);
+  const names = [];
+  for (const subdir of ["packages", "apps"]) {
+    const subdirPath = path4.join(absRepoPath, subdir);
+    if (!fs.existsSync(subdirPath)) {
+      continue;
+    }
+    for (const entry of fs.readdirSync(subdirPath)) {
+      const pkgJsonPath = path4.join(subdirPath, entry, "package.json");
+      if (!fs.existsSync(pkgJsonPath)) {
+        continue;
+      }
+      try {
+        const json = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+        if (json.name) {
+          names.push(json.name);
+        }
+      } catch {
+      }
+    }
+  }
+  return names;
+}
+function scanAllPackages(workspaceRoot, config) {
+  const results = [];
+  const topLevelDirs = ["platform", "plugins", "infra", "templates", "installer", "sites"];
+  for (const topDir of topLevelDirs) {
+    const topDirPath = path4.join(workspaceRoot, topDir);
+    if (!fs.existsSync(topDirPath)) {
+      continue;
+    }
+    for (const repoEntry of fs.readdirSync(topDirPath)) {
+      const repoPath = path4.join(topDirPath, repoEntry);
+      const repoRelPath = `${topDir}/${repoEntry}`;
+      let isDir;
+      try {
+        isDir = fs.statSync(repoPath).isDirectory();
+      } catch {
+        continue;
+      }
+      if (!isDir) {
+        continue;
+      }
+      const categoryResult = detectCategory(repoRelPath, config);
+      for (const subdir of ["packages", "apps"]) {
+        const subdirPath = path4.join(repoPath, subdir);
+        if (!fs.existsSync(subdirPath)) {
+          continue;
+        }
+        for (const pkgEntry of fs.readdirSync(subdirPath)) {
+          const pkgJsonPath = path4.join(subdirPath, pkgEntry, "package.json");
+          if (!fs.existsSync(pkgJsonPath)) {
+            continue;
+          }
+          try {
+            const json = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+            if (json.name) {
+              results.push({
+                name: json.name,
+                repoPath: repoRelPath,
+                category: categoryResult.category,
+                packageJsonPath: pkgJsonPath
+              });
+            }
+          } catch {
+          }
+        }
+      }
+    }
+  }
+  return results;
+}
+async function checkSdkOnlyDeps(repoPath, _config, workspaceRoot) {
+  const violations = [];
+  const absRepoPath = path4.resolve(workspaceRoot, repoPath);
+  const internalPackageNames = new Set(getRepoPackageNames(workspaceRoot, repoPath));
+  const packageJsonPaths = findPackageJsonPaths(absRepoPath);
+  for (const pkgJsonPath of packageJsonPaths) {
+    let json;
+    try {
+      json = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+    } catch {
+      continue;
+    }
+    const deps = Object.keys(json.dependencies ?? {});
+    const packageName = json.name ?? path4.basename(path4.dirname(pkgJsonPath));
+    const relPath = path4.relative(workspaceRoot, pkgJsonPath);
+    for (const dep of deps) {
+      if (!dep.startsWith("@kb-labs/")) {
+        continue;
+      }
+      if (dep === "@kb-labs/sdk") {
+        continue;
+      }
+      if (internalPackageNames.has(dep)) {
+        continue;
+      }
+      violations.push({
+        rule: "sdk-only-deps",
+        severity: "error",
+        message: `${packageName} imports ${dep} directly`,
+        package: packageName,
+        detail: `Plugins must depend only on @kb-labs/sdk. Move needed types to SDK or use SDK re-exports.`,
+        file: relPath
+      });
+    }
+  }
+  return violations;
+}
+function findPackageJsonPaths(absRepoPath) {
+  const results = [];
+  for (const subdir of ["packages", "apps"]) {
+    const subdirPath = path4.join(absRepoPath, subdir);
+    if (!fs.existsSync(subdirPath)) {
+      continue;
+    }
+    for (const entry of fs.readdirSync(subdirPath)) {
+      const pkgJsonPath = path4.join(subdirPath, entry, "package.json");
+      if (fs.existsSync(pkgJsonPath)) {
+        results.push(pkgJsonPath);
+      }
+    }
+  }
+  return results;
+}
+async function checkBoundary(repoPath, config, workspaceRoot) {
+  const violations = [];
+  const { detectCategory: detectCategory2 } = await Promise.resolve().then(() => (init_category_resolver(), category_resolver_exports));
+  const categoryResult = detectCategory2(repoPath, config);
+  const category = categoryResult.category;
+  if (!category) {
+    return violations;
+  }
+  const boundaryRuleConfig = config.rules["boundary-check"]?.config;
+  const allowedCategories = boundaryRuleConfig?.allowed?.[category] ?? [];
+  if (allowedCategories.includes("sdk-only")) {
+    return checkSdkOnlyDeps(repoPath, config, workspaceRoot);
+  }
+  const packageMap = buildPackageMap(workspaceRoot, config);
+  const internalPackageNames = new Set(getRepoPackageNames(workspaceRoot, repoPath));
+  const absRepoPath = path4.resolve(workspaceRoot, repoPath);
+  for (const pkgJsonPath of findPackageJsonPaths2(absRepoPath)) {
+    let json;
+    try {
+      json = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+    } catch {
+      continue;
+    }
+    const deps = Object.keys(json.dependencies ?? {});
+    const packageName = json.name ?? path4.basename(path4.dirname(pkgJsonPath));
+    const relPath = path4.relative(workspaceRoot, pkgJsonPath);
+    for (const dep of deps) {
+      if (!dep.startsWith("@kb-labs/")) {
+        continue;
+      }
+      if (internalPackageNames.has(dep)) {
+        continue;
+      }
+      const depCategory = packageMap.get(dep);
+      if (depCategory === void 0 || depCategory === null) {
+        continue;
+      }
+      if (!allowedCategories.includes(depCategory)) {
+        violations.push({
+          rule: "boundary-check",
+          severity: "error",
+          message: `${packageName} depends on ${dep} (category: ${depCategory ?? "unknown"})`,
+          package: packageName,
+          detail: `Category "${category}" may only depend on: ${allowedCategories.join(", ")}`,
+          file: relPath
+        });
+      }
+    }
+  }
+  return violations;
+}
+function findPackageJsonPaths2(absRepoPath) {
+  const results = [];
+  for (const subdir of ["packages", "apps"]) {
+    const subdirPath = path4.join(absRepoPath, subdir);
+    if (!fs.existsSync(subdirPath)) {
+      continue;
+    }
+    for (const entry of fs.readdirSync(subdirPath)) {
+      const pkgJsonPath = path4.join(subdirPath, entry, "package.json");
+      if (fs.existsSync(pkgJsonPath)) {
+        results.push(pkgJsonPath);
+      }
+    }
+  }
+  return results;
+}
+
+// src/checks/symbol-extractor.ts
+var RegexSymbolExtractor = class {
+  extract(dtsContent) {
+    const symbols = /* @__PURE__ */ new Set();
+    for (const m of dtsContent.matchAll(/^export\s+(?:async\s+)?function\s+(\w+)/gm)) {
+      symbols.add(m[1]);
+    }
+    for (const m of dtsContent.matchAll(/^export\s+(?:abstract\s+)?class\s+(\w+)/gm)) {
+      symbols.add(m[1]);
+    }
+    for (const m of dtsContent.matchAll(/^export\s+(?:type\s+|interface\s+)(\w+)/gm)) {
+      symbols.add(m[1]);
+    }
+    for (const m of dtsContent.matchAll(/^export\s+(?:const|let|var)\s+(\w+)/gm)) {
+      symbols.add(m[1]);
+    }
+    for (const m of dtsContent.matchAll(/^export\s+(?:const\s+)?enum\s+(\w+)/gm)) {
+      symbols.add(m[1]);
+    }
+    for (const m of dtsContent.matchAll(/^export\s+\{([^}]+)\}/gm)) {
+      const entries = m[1].split(",").map((s) => s.trim());
+      for (const entry of entries) {
+        const asMatch = entry.match(/\w+\s+as\s+(\w+)/);
+        if (asMatch) {
+          symbols.add(asMatch[1]);
+        } else {
+          const nameMatch = entry.match(/^(\w+)/);
+          if (nameMatch) {
+            symbols.add(nameMatch[1]);
+          }
+        }
+      }
+    }
+    if (/^export\s+default\s+/m.test(dtsContent)) {
+      symbols.add("default");
+    }
+    return symbols;
+  }
+};
+var defaultSymbolExtractor = new RegexSymbolExtractor();
+
+// src/checks/api-compat-check.ts
+var SNAPSHOTS_DIR = ".kb/api-snapshots";
+async function checkApiCompat(repoPath, _config, workspaceRoot) {
+  const violations = [];
+  const absRepoPath = path4.resolve(workspaceRoot, repoPath);
+  const packageJsonPaths = findPackageJsonPaths3(absRepoPath);
+  for (const pkgJsonPath of packageJsonPaths) {
+    let json;
+    try {
+      json = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+    } catch {
+      continue;
+    }
+    if (!json.name || !json.version) {
+      continue;
+    }
+    const pkgName = json.name;
+    const currentVersion = json.version;
+    const snapshotPath = getSnapshotPath(workspaceRoot, pkgName);
+    const pkgDir = path4.dirname(pkgJsonPath);
+    const currentSymbols = extractSymbolsFromDist(pkgDir);
+    if (!fs.existsSync(snapshotPath)) {
+      console.warn(
+        `[policy] api-compat: No snapshot for ${pkgName} \u2014 run 'policy update-snapshots' to create one.`
+      );
+      continue;
+    }
+    let snapshot;
+    try {
+      snapshot = JSON.parse(fs.readFileSync(snapshotPath, "utf-8"));
+    } catch {
+      console.warn(`[policy] api-compat: Could not read snapshot for ${pkgName}, skipping.`);
+      continue;
+    }
+    const snapshotSymbols = new Set(snapshot.symbols);
+    const relPath = path4.relative(workspaceRoot, pkgJsonPath);
+    const removed = [];
+    for (const sym of snapshotSymbols) {
+      if (!currentSymbols.has(sym)) {
+        removed.push(sym);
+      }
+    }
+    if (removed.length > 0) {
+      const currentMajor = parseMajor(currentVersion);
+      const snapshotMajor = parseMajor(snapshot.version);
+      if (currentMajor <= snapshotMajor) {
+        violations.push({
+          rule: "api-compat-check",
+          severity: "error",
+          message: `${pkgName} removed exported symbols without major version bump`,
+          package: pkgName,
+          detail: `Removed: ${removed.join(", ")}. Bump major version (current: ${currentVersion}, snapshot: ${snapshot.version}) or restore symbols.`,
+          file: relPath
+        });
+      }
+    }
+  }
+  return violations;
+}
+function extractSymbolsFromDist(pkgDir) {
+  const distDir = path4.join(pkgDir, "dist");
+  const symbols = /* @__PURE__ */ new Set();
+  if (!fs.existsSync(distDir)) {
+    return symbols;
+  }
+  const dtsFiles = findDtsFiles(distDir);
+  for (const dtsFile of dtsFiles) {
+    const content = fs.readFileSync(dtsFile, "utf-8");
+    for (const sym of defaultSymbolExtractor.extract(content)) {
+      symbols.add(sym);
+    }
+  }
+  return symbols;
+}
+function findDtsFiles(dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path4.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findDtsFiles(fullPath));
+    } else if (entry.name.endsWith(".d.ts")) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+function getSnapshotPath(workspaceRoot, packageName) {
+  const safeName = packageName.replace(/\//g, "__").replace(/@/g, "");
+  const snapshotsDir = path4.join(workspaceRoot, SNAPSHOTS_DIR);
+  if (!fs.existsSync(snapshotsDir)) {
+    fs.mkdirSync(snapshotsDir, { recursive: true });
+  }
+  return path4.join(snapshotsDir, `${safeName}.json`);
+}
+function parseMajor(version) {
+  return parseInt(version.split(".")[0] ?? "0", 10);
+}
+function findPackageJsonPaths3(absRepoPath) {
+  const results = [];
+  for (const subdir of ["packages", "apps"]) {
+    const subdirPath = path4.join(absRepoPath, subdir);
+    if (!fs.existsSync(subdirPath)) {
+      continue;
+    }
+    for (const entry of fs.readdirSync(subdirPath)) {
+      const pkgJsonPath = path4.join(subdirPath, entry, "package.json");
+      if (fs.existsSync(pkgJsonPath)) {
+        results.push(pkgJsonPath);
+      }
+    }
+  }
+  return results;
+}
+async function checkNoRollback(repoPath, _config, workspaceRoot) {
+  const violations = [];
+  const absRepoPath = path4.resolve(workspaceRoot, repoPath);
+  const packageJsonPaths = findPackageJsonPaths4(absRepoPath);
+  for (const pkgJsonPath of packageJsonPaths) {
+    let json;
+    try {
+      json = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+    } catch {
+      continue;
+    }
+    if (!json.name || !json.version) {
+      continue;
+    }
+    if (json.private) {
+      continue;
+    }
+    const packageName = json.name;
+    const currentVersion = json.version;
+    const relPath = path4.relative(workspaceRoot, pkgJsonPath);
+    const publishedVersion = getPublishedVersion(packageName);
+    if (publishedVersion === null) {
+      continue;
+    }
+    if (!semver.gte(currentVersion, publishedVersion)) {
+      violations.push({
+        rule: "no-rollback",
+        severity: "error",
+        message: `${packageName} version ${currentVersion} is less than published ${publishedVersion}`,
+        package: packageName,
+        detail: `Cannot decrease version once published to npm. Restore to ${publishedVersion} or higher.`,
+        file: relPath
+      });
+    }
+  }
+  return violations;
+}
+function getPublishedVersion(packageName) {
+  const result = spawnSync("npm", ["show", packageName, "version", "--silent"], {
+    timeout: 1e4,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  if (result.error || result.status !== 0) {
+    return null;
+  }
+  return semver.valid(result.stdout.trim()) ?? null;
+}
+function findPackageJsonPaths4(absRepoPath) {
+  const results = [];
+  for (const subdir of ["packages", "apps"]) {
+    const subdirPath = path4.join(absRepoPath, subdir);
+    if (!fs.existsSync(subdirPath)) {
+      continue;
+    }
+    for (const entry of fs.readdirSync(subdirPath)) {
+      const pkgJsonPath = path4.join(subdirPath, entry, "package.json");
+      if (fs.existsSync(pkgJsonPath)) {
+        results.push(pkgJsonPath);
+      }
+    }
+  }
+  return results;
+}
+
+// src/core/policy-runner.ts
+var RULE_CHECKS = {
+  "sdk-only-deps": checkSdkOnlyDeps,
+  "boundary-check": checkBoundary,
+  "no-breaking-without-major": checkApiCompat,
+  "no-rollback": checkNoRollback,
+  "api-compat-check": checkApiCompat
+};
+async function runChecks(repos, config, workspaceRoot) {
+  const repoResults = [];
+  for (const repo of repos) {
+    const violations = [];
+    const passed = [];
+    const rulesToRun = repo.rules;
+    for (const rule of rulesToRun) {
+      const checkFn = RULE_CHECKS[rule];
+      if (!checkFn) {
+        console.warn(`[policy] Unknown rule: ${rule} (skipping)`);
+        continue;
+      }
+      let ruleViolations;
+      try {
+        ruleViolations = await checkFn(repo.path, config, workspaceRoot);
+      } catch (err) {
+        console.warn(`[policy] Rule '${rule}' threw an unexpected error (skipping): ${err.message}`);
+        continue;
+      }
+      if (ruleViolations.length === 0) {
+        passed.push(rule);
+      } else {
+        violations.push(...ruleViolations.map((v) => ({ ...v, rule })));
+      }
+    }
+    repoResults.push({
+      path: repo.path,
+      category: repo.category,
+      violations,
+      passed
+    });
+  }
+  const totalViolations = repoResults.reduce((sum, r) => sum + r.violations.length, 0);
+  const failedRepos = repoResults.filter((r) => r.violations.length > 0).length;
+  return {
+    passed: totalViolations === 0,
+    repos: repoResults,
+    summary: {
+      total: repos.length,
+      passed: repos.length - failedRepos,
+      failed: failedRepos,
+      violations: totalViolations
+    }
+  };
+}
+var pluginPermissions = combinePermissions().withFs({
+  mode: "read",
+  allow: [".", ".kb/api-snapshots/**"]
+}).withQuotas({
+  timeoutMs: 6e4,
+  memoryMb: 256
+}).build();
+var detectPermissions = combinePermissions().withFs({ mode: "read", allow: ["."] }).withQuotas({ timeoutMs: 15e3, memoryMb: 128 }).build();
+var checkPermissions = combinePermissions().withFs({
+  mode: "read",
+  allow: [".", ".kb/api-snapshots/**"]
+}).withFs({
+  mode: "readWrite",
+  allow: [".kb/api-snapshots/**"]
+}).withQuotas({ timeoutMs: 6e4, memoryMb: 256 }).build();
+var snapshotPermissions = combinePermissions().withFs({ mode: "read", allow: ["."] }).withFs({ mode: "readWrite", allow: [".kb/api-snapshots/**"] }).withQuotas({ timeoutMs: 3e4, memoryMb: 128 }).build();
+var manifest = {
+  schema: "kb.plugin/3",
+  id: "@kb-labs/policy",
+  version: "0.1.0",
+  configSection: "policy",
+  display: {
+    name: "Policy Enforcer",
+    description: "Enforces workspace-level development policies per category. Detects repo categories, resolves applicable rules, and validates compliance.",
+    tags: ["policy", "governance", "boundaries", "sdk-only", "api-compat"]
+  },
+  cli: {
+    commands: [
+      {
+        id: "policy:detect",
+        group: "policy",
+        describe: "Detect policy category for changed or specified repos",
+        longDescription: "Determines the category for repos based on git changes or a specified path, then resolves applicable policy rules.",
+        handler: "./cli/commands/detect.js#default",
+        handlerPath: "./cli/commands/detect.js",
+        flags: defineCommandFlags({
+          path: {
+            type: "string",
+            description: "Repo path to check (relative to workspace root). Defaults to git diff."
+          },
+          json: {
+            type: "boolean",
+            description: "Output as JSON",
+            default: false
+          }
+        }),
+        permissions: detectPermissions
+      },
+      {
+        id: "policy:check",
+        group: "policy",
+        describe: "Run policy checks for changed repos or a specific path",
+        longDescription: "Runs all applicable policy rules for detected repos. Exits with code 1 on violations. Use in CI or pnpm done pipeline.",
+        handler: "./cli/commands/check.js#default",
+        handlerPath: "./cli/commands/check.js",
+        flags: defineCommandFlags({
+          path: {
+            type: "string",
+            description: "Repo path to check (relative to workspace root). Defaults to git diff."
+          },
+          json: {
+            type: "boolean",
+            description: "Output as JSON",
+            default: false
+          }
+        }),
+        permissions: checkPermissions
+      },
+      {
+        id: "policy:rules",
+        group: "policy",
+        describe: "Show all configured policy rules and their categories",
+        handler: "./cli/commands/rules.js#default",
+        handlerPath: "./cli/commands/rules.js",
+        flags: defineCommandFlags({
+          json: {
+            type: "boolean",
+            description: "Output as JSON",
+            default: false
+          }
+        }),
+        permissions: detectPermissions
+      },
+      {
+        id: "policy:snapshot",
+        group: "policy",
+        describe: "Create or update API snapshot for a repo (run after npm publish)",
+        longDescription: "Extracts exported symbols from dist/*.d.ts files and saves them to .kb/api-snapshots/. Used by api-compat-check to detect breaking changes.",
+        handler: "./cli/commands/snapshot.js#default",
+        handlerPath: "./cli/commands/snapshot.js",
+        flags: defineCommandFlags({
+          path: {
+            type: "string",
+            description: "Repo path (relative to workspace root)",
+            required: true
+          }
+        }),
+        permissions: snapshotPermissions
+      }
+    ]
+  },
+  permissions: pluginPermissions
+};
+
+export { buildPackageMap, detectCategories, detectCategory, getRepoPackageNames, manifest, runChecks };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map