@setzkasten/cli 0.1.0-rc.1

package/src/lib/policy.js

@@ -0,0 +1,271 @@
+function asObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+
+  return value;
+}
+
+function asString(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function asStringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter((entry) => typeof entry === "string" && entry.length > 0);
+}
+
+function readProjectDomains(manifest) {
+  const project = asObject(manifest.project);
+  if (!project) {
+    return [];
+  }
+
+  return asStringArray(project.domains);
+}
+
+function makeOfferingKey(offeringId, offeringVersion) {
+  return `${offeringId}@${offeringVersion}`;
+}
+
+function readRequiredModifications(fontUsage) {
+  const usage = asObject(fontUsage);
+  if (!usage) {
+    return [];
+  }
+
+  const candidates = [
+    usage.required_modifications,
+    usage.modifications_required,
+    usage.requiredModificationKinds,
+  ];
+
+  for (const candidate of candidates) {
+    const values = asStringArray(candidate);
+    if (values.length > 0) {
+      return values;
+    }
+  }
+
+  return [];
+}
+
+function isSelfHostingUsage(fontUsage) {
+  const usage = asObject(fontUsage);
+  if (!usage) {
+    return false;
+  }
+
+  if (usage.self_hosting === true) {
+    return true;
+  }
+
+  const hosting = usage.hosting;
+  if (typeof hosting === "string") {
+    return hosting === "self_hosting";
+  }
+
+  if (Array.isArray(hosting)) {
+    return hosting.includes("self_hosting");
+  }
+
+  return false;
+}
+
+function findRight(rights, rightType) {
+  return rights.find((right) => typeof right.right_type === "string" && right.right_type === rightType) ?? null;
+}
+
+function makeDecision(reasons) {
+  if (reasons.some((reason) => reason.severity === "escalate")) {
+    return "escalate";
+  }
+
+  if (reasons.some((reason) => reason.severity === "warn")) {
+    return "warn";
+  }
+
+  return "allow";
+}
+
+function normalizeRights(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry));
+}
+
+export function evaluatePolicy(manifest) {
+  const reasons = [];
+  const evidenceRequired = new Set();
+
+  const projectDomains = readProjectDomains(manifest);
+  const fonts = Array.isArray(manifest.fonts) ? manifest.fonts : [];
+  const instances = Array.isArray(manifest.license_instances) ? manifest.license_instances : [];
+  const offerings = Array.isArray(manifest.license_offerings) ? manifest.license_offerings : [];
+
+  const instancesById = new Map();
+  for (const instance of instances) {
+    const instanceId = asString(instance.license_id);
+    if (instanceId) {
+      instancesById.set(instanceId, instance);
+    }
+  }
+
+  const offeringsByKey = new Map();
+  for (const offering of offerings) {
+    const offeringId = asString(offering.offering_id);
+    const offeringVersion = asString(offering.offering_version);
+
+    if (offeringId && offeringVersion) {
+      offeringsByKey.set(makeOfferingKey(offeringId, offeringVersion), offering);
+    }
+  }
+
+  for (const font of fonts) {
+    const fontId = asString(font.font_id) ?? "unknown_font";
+    const source = asObject(font.source);
+    const sourceType = asString(source?.type);
+
+    const instanceIds = asStringArray(font.license_instance_ids);
+    const activeInstanceId = asString(font.active_license_instance_id) ?? instanceIds[0] ?? null;
+    const instance = activeInstanceId ? instancesById.get(activeInstanceId) ?? null : null;
+
+    if (sourceType === "byo") {
+      if (!instance) {
+        reasons.push({
+          code: "BYO_NO_LICENSE_INSTANCE",
+          severity: "warn",
+          message: `BYO font '${fontId}' has no linked license instance.`,
+          context: { font_id: fontId },
+        });
+        evidenceRequired.add("license_instances[].evidence[]");
+      } else {
+        const evidence = Array.isArray(instance.evidence) ? instance.evidence : [];
+        if (evidence.length === 0) {
+          reasons.push({
+            code: "BYO_NO_EVIDENCE",
+            severity: "warn",
+            message: `BYO font '${fontId}' has no evidence attached.`,
+            context: { font_id: fontId, license_id: activeInstanceId },
+          });
+          evidenceRequired.add("license_instances[].evidence[]");
+        }
+      }
+    }
+
+    if (!instance) {
+      continue;
+    }
+
+    const status = asString(instance.status);
+    if (status && status !== "active") {
+      reasons.push({
+        code: "LICENSE_STATUS_NOT_ACTIVE",
+        severity: "escalate",
+        message: `License instance '${activeInstanceId}' is '${status}', not active.`,
+        context: { license_id: activeInstanceId, status },
+      });
+    }
+
+    const scope = asObject(instance.scope);
+    const scopeDomains = asStringArray(scope?.domains);
+
+    if (projectDomains.length > 0 && scopeDomains.length > 0) {
+      for (const domain of projectDomains) {
+        if (!scopeDomains.includes(domain)) {
+          reasons.push({
+            code: "DOMAIN_OUT_OF_SCOPE",
+            severity: "warn",
+            message: `Project domain '${domain}' is not covered by license scope for '${activeInstanceId}'.`,
+            context: { license_id: activeInstanceId, domain },
+          });
+        }
+      }
+    }
+
+    const offeringRef = asObject(instance.offering_ref);
+    const offeringId = asString(offeringRef?.offering_id);
+    const offeringVersion = asString(offeringRef?.offering_version);
+
+    let offering = null;
+    if (offeringId && offeringVersion) {
+      offering = offeringsByKey.get(makeOfferingKey(offeringId, offeringVersion)) ?? null;
+      if (!offering) {
+        reasons.push({
+          code: "OFFERING_REFERENCE_MISSING",
+          severity: "warn",
+          message: `Offering '${offeringId}@${offeringVersion}' referenced by '${activeInstanceId}' is missing.`,
+          context: { license_id: activeInstanceId, offering_id: offeringId, offering_version: offeringVersion },
+        });
+      }
+    }
+
+    if (!offering) {
+      continue;
+    }
+
+    const rights = normalizeRights(offering.rights);
+
+    if (isSelfHostingUsage(font.usage)) {
+      const selfHostingRight = findRight(rights, "distribution_self_hosting");
+      const cdnHostingRight = findRight(rights, "distribution_cdn_hosting");
+
+      const selfHostingAllowed = selfHostingRight?.allowed === true;
+      const cdnOnly = cdnHostingRight?.allowed === true && !selfHostingAllowed;
+
+      if (cdnOnly) {
+        reasons.push({
+          code: "SELF_HOSTING_NOT_ALLOWED",
+          severity: "warn",
+          message: `Font '${fontId}' appears self-hosted but offering allows CDN-only distribution.`,
+          context: { font_id: fontId, license_id: activeInstanceId },
+        });
+      }
+    }
+
+    const requiredModifications = readRequiredModifications(font.usage);
+    if (requiredModifications.length > 0) {
+      const modificationRight = findRight(rights, "modification");
+
+      if (!modificationRight || modificationRight.allowed !== true) {
+        reasons.push({
+          code: "MODIFICATION_NOT_ALLOWED",
+          severity: "escalate",
+          message: `Font '${fontId}' requires modification but offering does not allow it.`,
+          context: { font_id: fontId, license_id: activeInstanceId, required: requiredModifications },
+        });
+        continue;
+      }
+
+      const allowedKinds = asStringArray(modificationRight.modification_kinds);
+      if (allowedKinds.length > 0) {
+        const disallowedKinds = requiredModifications.filter((kind) => !allowedKinds.includes(kind));
+
+        if (disallowedKinds.length > 0) {
+          reasons.push({
+            code: "MODIFICATION_KIND_NOT_ALLOWED",
+            severity: "escalate",
+            message: `Font '${fontId}' requires unsupported modification kinds.`,
+            context: {
+              font_id: fontId,
+              license_id: activeInstanceId,
+              required: requiredModifications,
+              disallowed: disallowedKinds,
+            },
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    decision: makeDecision(reasons),
+    reasons,
+    evidence_required: Array.from(evidenceRequired).sort((a, b) => a.localeCompare(b)),
+  };
+}

package/src/lib/quote.js

@@ -0,0 +1,219 @@
+import { canonicalStringify, nowIso, roundMoney, sha256Hex } from "./core.js";
+
+function asObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+
+  return value;
+}
+
+function asString(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function asNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+
+  return null;
+}
+
+function asMetricLimits(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry));
+}
+
+function matchesWhen(when, instance) {
+  const metricType = asString(when.metric_type);
+  const period = asString(when.period);
+
+  const limits = asMetricLimits(instance.metric_limits).filter((limit) => {
+    const limitMetricType = asString(limit.metric_type);
+    const limitPeriod = asString(limit.period);
+
+    if (metricType && limitMetricType !== metricType) {
+      return false;
+    }
+
+    if (period && limitPeriod !== period) {
+      return false;
+    }
+
+    return true;
+  });
+
+  if ((metricType || period) && limits.length === 0) {
+    return false;
+  }
+
+  const gte = asNumber(when.gte);
+  const gt = asNumber(when.gt);
+  const lte = asNumber(when.lte);
+  const lt = asNumber(when.lt);
+  const eq = asNumber(when.eq);
+
+  if (gte === null && gt === null && lte === null && lt === null && eq === null) {
+    return true;
+  }
+
+  const candidates = limits.length > 0 ? limits : asMetricLimits(instance.metric_limits);
+
+  return candidates.some((candidate) => {
+    const value = asNumber(candidate.limit);
+    if (value === null) {
+      return false;
+    }
+
+    if (gte !== null && value < gte) {
+      return false;
+    }
+
+    if (gt !== null && value <= gt) {
+      return false;
+    }
+
+    if (lte !== null && value > lte) {
+      return false;
+    }
+
+    if (lt !== null && value >= lt) {
+      return false;
+    }
+
+    if (eq !== null && value !== eq) {
+      return false;
+    }
+
+    return true;
+  });
+}
+
+function makeOfferingKey(offeringId, offeringVersion) {
+  return `${offeringId}@${offeringVersion}`;
+}
+
+function evaluateAmountForInstance(instance, offering) {
+  const priceFormula = asObject(offering.price_formula);
+  if (!priceFormula) {
+    throw new Error("price_formula missing for offering.");
+  }
+
+  const currency = asString(priceFormula.currency);
+  const basePrice = asNumber(priceFormula.base_price);
+
+  if (!currency || basePrice === null) {
+    throw new Error("price_formula must include currency and base_price.");
+  }
+
+  let amount = basePrice;
+
+  const rules = Array.isArray(priceFormula.rules)
+    ? priceFormula.rules.filter((rule) => {
+        return Boolean(rule) && typeof rule === "object" && !Array.isArray(rule);
+      })
+    : [];
+
+  for (const rule of rules) {
+    const when = asObject(rule.when);
+
+    if (when && !matchesWhen(when, instance)) {
+      continue;
+    }
+
+    const multiplier = asNumber(rule.multiplier) ?? 1;
+    const add = asNumber(rule.add) ?? 0;
+
+    amount = roundMoney(amount * multiplier + add);
+  }
+
+  return {
+    currency,
+    amount: roundMoney(amount),
+  };
+}
+
+export function generateQuote(manifest) {
+  const offerings = Array.isArray(manifest.license_offerings) ? manifest.license_offerings : [];
+  const instances = Array.isArray(manifest.license_instances) ? manifest.license_instances : [];
+
+  const offeringsByKey = new Map();
+
+  for (const offering of offerings) {
+    const offeringId = asString(offering.offering_id);
+    const offeringVersion = asString(offering.offering_version);
+
+    if (offeringId && offeringVersion) {
+      offeringsByKey.set(makeOfferingKey(offeringId, offeringVersion), offering);
+    }
+  }
+
+  const lineItems = [];
+  const skipped = [];
+
+  for (const instance of instances) {
+    const licenseId = asString(instance.license_id);
+    if (!licenseId) {
+      continue;
+    }
+
+    const status = asString(instance.status);
+    if (status && status !== "active") {
+      skipped.push(`${licenseId}:status=${status}`);
+      continue;
+    }
+
+    const offeringRef = asObject(instance.offering_ref);
+    const offeringId = asString(offeringRef?.offering_id);
+    const offeringVersion = asString(offeringRef?.offering_version);
+
+    if (!offeringId || !offeringVersion) {
+      skipped.push(`${licenseId}:offering_ref_missing`);
+      continue;
+    }
+
+    const offering = offeringsByKey.get(makeOfferingKey(offeringId, offeringVersion));
+    if (!offering) {
+      skipped.push(`${licenseId}:offering_not_found`);
+      continue;
+    }
+
+    const evaluated = evaluateAmountForInstance(instance, offering);
+
+    lineItems.push({
+      license_id: licenseId,
+      offering_id: offeringId,
+      offering_version: offeringVersion,
+      currency: evaluated.currency,
+      amount: evaluated.amount,
+    });
+  }
+
+  lineItems.sort((a, b) => a.license_id.localeCompare(b.license_id));
+
+  const totals = {};
+  for (const lineItem of lineItems) {
+    const previous = totals[lineItem.currency] ?? 0;
+    totals[lineItem.currency] = roundMoney(previous + lineItem.amount);
+  }
+
+  skipped.sort((a, b) => a.localeCompare(b));
+
+  const fingerprintTarget = {
+    totals,
+    line_items: lineItems,
+    skipped,
+  };
+
+  return {
+    generated_at: nowIso(),
+    totals,
+    line_items: lineItems,
+    skipped,
+    deterministic_hash: sha256Hex(canonicalStringify(fingerprintTarget)),
+  };
+}

package/src/lib/scanner.js

@@ -0,0 +1,176 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { nowIso } from "./core.js";
+
+const DEFAULT_IGNORED_DIRS = new Set([
+  ".git",
+  "node_modules",
+  ".setzkasten",
+  "dist",
+  "coverage",
+  ".next",
+  ".turbo",
+]);
+
+const TEXT_FILE_EXTENSIONS = new Set([
+  ".css",
+  ".scss",
+  ".sass",
+  ".less",
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".html",
+  ".htm",
+  ".md",
+  ".json",
+  ".yaml",
+  ".yml",
+  ".txt",
+]);
+
+function deepClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function normalizeFonts(manifest) {
+  return Array.isArray(manifest.fonts) ? manifest.fonts : [];
+}
+
+function shouldScanFile(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  return TEXT_FILE_EXTENSIONS.has(extension);
+}
+
+async function collectScanFiles(rootPath) {
+  const files = [];
+
+  async function walk(dirPath) {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) {
+        if (entry.isDirectory() && !DEFAULT_IGNORED_DIRS.has(entry.name)) {
+          await walk(path.join(dirPath, entry.name));
+        }
+        continue;
+      }
+
+      const fullPath = path.join(dirPath, entry.name);
+
+      if (entry.isDirectory()) {
+        if (!DEFAULT_IGNORED_DIRS.has(entry.name)) {
+          await walk(fullPath);
+        }
+        continue;
+      }
+
+      if (!entry.isFile() || !shouldScanFile(fullPath)) {
+        continue;
+      }
+
+      const fileStat = await stat(fullPath);
+      if (fileStat.size > 2 * 1024 * 1024) {
+        continue;
+      }
+
+      files.push(fullPath);
+    }
+  }
+
+  await walk(rootPath);
+  return files;
+}
+
+function relativeTo(rootPath, targetPath) {
+  const relativePath = path.relative(rootPath, targetPath);
+  return relativePath.length > 0 ? relativePath : ".";
+}
+
+export async function scanProject(input) {
+  const rootPath = path.resolve(input.rootPath);
+  const maxMatchedPathsPerFont = input.maxMatchedPathsPerFont ?? 30;
+
+  const fonts = normalizeFonts(input.manifest)
+    .map((font) => ({
+      font_id: typeof font.font_id === "string" ? font.font_id : "",
+      family_name: typeof font.family_name === "string" ? font.family_name : "",
+    }))
+    .filter((font) => font.font_id.length > 0 && font.family_name.length > 0);
+
+  const files = await collectScanFiles(rootPath);
+  const matches = new Map();
+
+  for (const font of fonts) {
+    matches.set(font.font_id, {
+      font_id: font.font_id,
+      family_name: font.family_name,
+      match_count: 0,
+      matched_paths: [],
+    });
+  }
+
+  for (const filePath of files) {
+    let content;
+
+    try {
+      content = await readFile(filePath, "utf8");
+    } catch {
+      continue;
+    }
+
+    const lowerContent = content.toLowerCase();
+
+    for (const font of fonts) {
+      if (!lowerContent.includes(font.family_name.toLowerCase())) {
+        continue;
+      }
+
+      const entry = matches.get(font.font_id);
+      if (!entry) {
+        continue;
+      }
+
+      entry.match_count += 1;
+      if (entry.matched_paths.length < maxMatchedPathsPerFont) {
+        entry.matched_paths.push(relativeTo(rootPath, filePath));
+      }
+    }
+  }
+
+  return {
+    scanned_at: nowIso(),
+    root_path: rootPath,
+    scanned_files_count: files.length,
+    font_matches: Object.fromEntries(Array.from(matches.entries())),
+  };
+}
+
+export function applyScanResultToManifest(manifest, scanResult) {
+  const draft = deepClone(manifest);
+  const fonts = Array.isArray(draft.fonts) ? draft.fonts : [];
+
+  for (const font of fonts) {
+    const fontId = typeof font.font_id === "string" ? font.font_id : "";
+    if (!fontId) {
+      continue;
+    }
+
+    const match = scanResult.font_matches[fontId];
+    const currentUsage =
+      font.usage && typeof font.usage === "object" && !Array.isArray(font.usage) ? font.usage : {};
+
+    font.usage = {
+      ...currentUsage,
+      scan: {
+        scanned_at: scanResult.scanned_at,
+        match_count: match?.match_count ?? 0,
+        matched_paths: match?.matched_paths ?? [],
+      },
+    };
+  }
+
+  draft.fonts = fonts;
+  return draft;
+}