@objectstack/lint 13.0.0 → 14.3.0

package/dist/index.js

@@ -1298,6 +1298,88 @@ function validateCapabilityReferences(stack) {
   return findings;
 }
 
+// src/validate-approval-approvers.ts
+import { ApproverType, APPROVAL_NODE_TYPE } from "@objectstack/spec/automation";
+var APPROVAL_ROLE_NOT_MEMBERSHIP_TIER = "approval-role-not-membership-tier";
+var APPROVAL_APPROVER_TYPE_UNKNOWN = "approval-approver-type-unknown";
+var APPROVAL_ESCALATION_REASSIGN_NO_TARGET = "approval-escalation-reassign-no-target";
+var MEMBERSHIP_TIERS = /* @__PURE__ */ new Set(["owner", "admin", "member", "guest"]);
+var TYPE_FIX = {
+  business_unit: "department",
+  bu: "department"
+};
+function asArray13(v) {
+  if (Array.isArray(v)) return v;
+  if (v && typeof v === "object") {
+    return Object.entries(v).map(([name, def]) => ({ name, ...def }));
+  }
+  return [];
+}
+function validateApprovalApprovers(stack) {
+  const findings = [];
+  if (!stack || typeof stack !== "object") return findings;
+  const flows = asArray13(stack.flows);
+  const validTypes = new Set(ApproverType.options);
+  for (let fi = 0; fi < flows.length; fi++) {
+    const flow = flows[fi];
+    if (!flow || typeof flow !== "object") continue;
+    const flowName = typeof flow.name === "string" ? flow.name : `(flow ${fi})`;
+    const nodes = Array.isArray(flow.nodes) ? flow.nodes : [];
+    for (let ni = 0; ni < nodes.length; ni++) {
+      const node = nodes[ni];
+      if (!node || node.type !== APPROVAL_NODE_TYPE) continue;
+      const nodeId = typeof node.id === "string" ? node.id : `(node ${ni})`;
+      const cfg = node.config ?? {};
+      const approvers = Array.isArray(cfg.approvers) ? cfg.approvers : [];
+      const where = `flow "${flowName}" \xB7 node "${nodeId}"`;
+      for (let ai = 0; ai < approvers.length; ai++) {
+        const a = approvers[ai];
+        if (!a || typeof a !== "object") continue;
+        const type = typeof a.type === "string" ? a.type : "";
+        const value = typeof a.value === "string" ? a.value : "";
+        const path = `flows[${fi}].nodes[${ni}].config.approvers[${ai}]`;
+        if (type && !validTypes.has(type)) {
+          const fix = TYPE_FIX[type];
+          findings.push({
+            severity: "warning",
+            rule: APPROVAL_APPROVER_TYPE_UNKNOWN,
+            where,
+            path: `${path}.type`,
+            message: `approver type '${type}' is not an ApproverType (${ApproverType.options.join(" | ")}).`,
+            hint: fix ? `Use the spec value: { type: '${fix}', value: '${value}' }.` : `Pick one of the spec values; unmapped types degrade to an inert '${type}:${value}' literal at runtime.`
+          });
+          continue;
+        }
+        if (type === "role" && value && !MEMBERSHIP_TIERS.has(value.toLowerCase())) {
+          findings.push({
+            severity: "warning",
+            rule: APPROVAL_ROLE_NOT_MEMBERSHIP_TIER,
+            where,
+            path: `${path}.value`,
+            message: `approver { type: 'role', value: '${value}' } resolves against the better-auth org-membership tier (sys_member.role: owner/admin/member) \u2014 '${value}' is not a membership tier, so this approver matches nobody and the request stalls.`,
+            hint: `If '${value}' is an org position, author { type: 'position', value: '${value}' } (resolved via sys_user_position, ADR-0090 D3). Keep type 'role' only for membership tiers (owner/admin/member).`
+          });
+        }
+      }
+      const escalation = cfg.escalation ?? null;
+      if (escalation && typeof escalation === "object" && escalation.action === "reassign") {
+        const target = typeof escalation.escalateTo === "string" ? escalation.escalateTo.trim() : "";
+        if (!target) {
+          findings.push({
+            severity: "warning",
+            rule: APPROVAL_ESCALATION_REASSIGN_NO_TARGET,
+            where,
+            path: `flows[${fi}].nodes[${ni}].config.escalation.escalateTo`,
+            message: `escalation.action is 'reassign' but escalateTo is empty \u2014 at runtime the escalation degrades to a notify and the request stays with the original approvers.`,
+            hint: `Set escalateTo to a position machine name (expanded via sys_user_position, ADR-0090 D3) or a specific user id, or change action to 'notify'.`
+          });
+        }
+      }
+    }
+  }
+  return findings;
+}
+
 // src/validate-security-posture.ts
 import { describeAnchorForbiddenBits } from "@objectstack/spec/security";
 var SECURITY_OWD_UNSET = "security-owd-unset";
@@ -1306,7 +1388,9 @@ var SECURITY_EXTERNAL_WIDER = "security-external-wider-than-internal";
 var SECURITY_WILDCARD_VAMA = "security-wildcard-vama";
 var SECURITY_ANCHOR_HIGH_PRIVILEGE = "security-anchor-high-privilege";
 var SECURITY_ROLE_WORD = "security-role-word";
+var SECURITY_BOOK_AUDIENCE_UNKNOWN_SET = "security-book-audience-unknown-set";
 var SECURITY_PRIVATE_NO_READSCOPE = "security-private-no-readscope";
+var SECURITY_MASTER_DETAIL_UNGRANTED = "security-master-detail-ungranted";
 var CANONICAL_OWD = ["private", "public_read", "public_read_write", "controlled_by_parent"];
 var OWD_ALIAS_FIX = {
   read: "public_read",
@@ -1319,7 +1403,7 @@ var OWD_WIDTH = {
   public_read: 1,
   public_read_write: 2
 };
-function asArray13(v) {
+function asArray14(v) {
   if (Array.isArray(v)) return v;
   if (v && typeof v === "object") {
     return Object.entries(v).map(([name, def]) => ({ name, ...def }));
@@ -1340,11 +1424,26 @@ function labelHasRoleWord(label) {
   if (typeof label !== "string") return false;
   return /\brole(s)?\b/i.test(label);
 }
+function refOf(def) {
+  const r = def.reference ?? def.reference_to;
+  return typeof r === "string" && r ? r : void 0;
+}
+function firstMasterDetailField(obj) {
+  for (const f of asArray14(obj.fields)) {
+    if (f.type === "master_detail") {
+      return { name: String(f.name ?? "?"), parent: refOf(f) };
+    }
+  }
+  return void 0;
+}
+function grantsObjectAccess(p) {
+  return p.allowRead === true || p.allowCreate === true || p.allowEdit === true || p.allowDelete === true || p.viewAllRecords === true || p.modifyAllRecords === true;
+}
 function validateSecurityPosture(stack) {
   const findings = [];
   if (!stack || typeof stack !== "object") return findings;
-  const objects = asArray13(stack.objects);
-  const permissionSets = asArray13(stack.permissions);
+  const objects = asArray14(stack.objects);
+  const permissionSets = asArray14(stack.permissions);
   for (let i = 0; i < objects.length; i++) {
     const obj = objects[i];
     if (!obj || typeof obj !== "object") continue;
@@ -1461,10 +1560,10 @@ function validateSecurityPosture(stack) {
     if (!obj || typeof obj !== "object" || isSystemObject(obj)) continue;
     const objName = typeof obj.name === "string" ? obj.name : `(object ${i})`;
     flagRole("object", obj.name, obj.label, `object "${objName}"`, `objects[${i}].name`);
-    for (const f of asArray13(obj.fields)) {
+    for (const f of asArray14(obj.fields)) {
       flagRole("field", f.name, f.label, `field "${objName}.${String(f.name ?? "?")}"`, `objects[${i}].fields.${String(f.name ?? "?")}.name`);
     }
-    for (const [ai, action] of asArray13(obj.actions).entries()) {
+    for (const [ai, action] of asArray14(obj.actions).entries()) {
       flagRole("action", action.name, action.label, `action "${objName}.${String(action.name ?? "?")}"`, `objects[${i}].actions[${ai}].name`);
     }
   }
@@ -1473,12 +1572,34 @@ function validateSecurityPosture(stack) {
     if (!ps || typeof ps !== "object") continue;
     flagRole("permission set", ps.name, ps.label, `permission set "${String(ps.name ?? i)}"`, `permissions[${i}].name`);
   }
-  for (const [i, pos] of asArray13(stack.positions).entries()) {
+  for (const [i, pos] of asArray14(stack.positions).entries()) {
     flagRole("position", pos.name, pos.label, `position "${String(pos.name ?? i)}"`, `positions[${i}].name`);
   }
-  for (const [i, app] of asArray13(stack.apps).entries()) {
+  for (const [i, app] of asArray14(stack.apps).entries()) {
     flagRole("app", app.name, app.label, `app "${String(app.name ?? i)}"`, `apps[${i}].name`);
   }
+  for (const [i, book] of asArray14(stack.books).entries()) {
+    flagRole("book", book.name, book.label, `book "${String(book.name ?? i)}"`, `books[${i}].name`);
+  }
+  const stackSetNames = new Set(
+    permissionSets.map((ps) => typeof ps.name === "string" ? ps.name : void 0).filter((n) => !!n)
+  );
+  for (const [i, book] of asArray14(stack.books).entries()) {
+    const audience = book.audience;
+    if (!audience || typeof audience !== "object") continue;
+    const setName = audience.permissionSet;
+    if (typeof setName !== "string" || setName.length === 0) continue;
+    if (!stackSetNames.has(setName)) {
+      findings.push({
+        severity: "warning",
+        rule: SECURITY_BOOK_AUDIENCE_UNKNOWN_SET,
+        where: `book "${String(book.name ?? i)}"`,
+        path: `books[${i}].audience.permissionSet`,
+        message: `book audience references permission set "${setName}", which this stack does not declare. The runtime fails closed \u2014 no holder means NO reader can open the book.`,
+        hint: `Gate the book on one of this package's own permission sets (ADR-0090 D9, e.g. its admin set), or fix the typo. Ignore if the set is intentionally provided by another installed package.`
+      });
+    }
+  }
   const privateObjects = new Set(
     objects.filter((o) => o && typeof o === "object" && !isSystemObject(o)).filter((o) => {
       const owd = owdOf(o);
@@ -1507,11 +1628,43 @@ function validateSecurityPosture(stack) {
       }
     }
   }
+  if (permissionSets.length > 0) {
+    const wildcardGrantsAll = permissionSets.some(
+      (ps) => grantsObjectAccess(ps.objects?.["*"] ?? {})
+    );
+    if (!wildcardGrantsAll) {
+      const grantedObjects = /* @__PURE__ */ new Set();
+      for (const ps of permissionSets) {
+        const objectsMap = ps.objects && typeof ps.objects === "object" ? ps.objects : {};
+        for (const [objName, rawPerm] of Object.entries(objectsMap)) {
+          if (objName === "*") continue;
+          if (grantsObjectAccess(rawPerm ?? {})) grantedObjects.add(objName);
+        }
+      }
+      for (let i = 0; i < objects.length; i++) {
+        const obj = objects[i];
+        if (!obj || typeof obj !== "object" || isSystemObject(obj)) continue;
+        const objName = typeof obj.name === "string" ? obj.name : "";
+        if (!objName || grantedObjects.has(objName)) continue;
+        const md = firstMasterDetailField(obj);
+        if (!md) continue;
+        const parentText = md.parent ? ` \u2192 "${md.parent}"` : "";
+        findings.push({
+          severity: "warning",
+          rule: SECURITY_MASTER_DETAIL_UNGRANTED,
+          where: `object "${objName}"`,
+          path: `objects[${i}].fields.${md.name}`,
+          message: `detail object "${objName}" (master_detail "${md.name}"${parentText}) has no object-level CRUD grant in any permission set. A master-detail child derives its RECORD-level access from the master (ADR-0055 controlled_by_parent), but object-level CRUD is a SEPARATE gate that is never derived \u2014 role-bound non-admin users are denied (403) before the parent-derived access is ever consulted (the silent "can't submit the subtable" trap).`,
+          hint: `Grant "${objName}" in at least one permission set that already grants its master${md.parent ? ` "${md.parent}"` : ""} \u2014 e.g. permissions[i].objects.${objName} = { allowRead: true, allowCreate: true, allowEdit: true }. If no role should ever touch it (a pure system/internal table), name it sys_* or set isSystem: true.`
+        });
+      }
+    }
+  }
   return findings;
 }
 
 // src/build-access-matrix.ts
-function asArray14(v) {
+function asArray15(v) {
   if (Array.isArray(v)) return v;
   if (v && typeof v === "object") {
     return Object.entries(v).map(([name, def]) => ({ name, ...def }));
@@ -1522,13 +1675,13 @@ function buildAccessMatrix(stack) {
   const entries = [];
   if (!stack || typeof stack !== "object") return { version: 1, entries };
   const owdByObject = /* @__PURE__ */ new Map();
-  for (const obj of asArray14(stack.objects)) {
+  for (const obj of asArray15(stack.objects)) {
     const name = typeof obj.name === "string" ? obj.name : "";
     if (!name) continue;
     const owd = obj.sharingModel ?? obj.security?.sharingModel;
     if (typeof owd === "string") owdByObject.set(name, owd);
   }
-  for (const ps of asArray14(stack.permissions)) {
+  for (const ps of asArray15(stack.permissions)) {
     const psName = typeof ps.name === "string" ? ps.name : "";
     if (!psName) continue;
     const objects = ps.objects && typeof ps.objects === "object" ? ps.objects : {};
@@ -1599,6 +1752,9 @@ function diffAccessMatrix(before, after) {
   return lines;
 }
 export {
+  APPROVAL_APPROVER_TYPE_UNKNOWN,
+  APPROVAL_ESCALATION_REASSIGN_NO_TARGET,
+  APPROVAL_ROLE_NOT_MEMBERSHIP_TIER,
   CAPABILITY_REFERENCE_UNKNOWN,
   CHART_CONFIG_MISSING,
   CHART_FIELD_UNKNOWN,
@@ -1610,6 +1766,7 @@ export {
   MEASURE_AGGREGATE_INCOHERENT,
   PAGE_SOURCE_CLASSNAME,
   SECURITY_ANCHOR_HIGH_PRIVILEGE,
+  SECURITY_BOOK_AUDIENCE_UNKNOWN_SET,
   SECURITY_EXTERNAL_WIDER,
   SECURITY_OWD_ALIAS,
   SECURITY_OWD_UNSET,
@@ -1630,6 +1787,7 @@ export {
   WIDGET_MEASURE_UNKNOWN,
   buildAccessMatrix,
   diffAccessMatrix,
+  validateApprovalApprovers,
   validateCapabilityReferences,
   validateFormLayout,
   validateJsxPages,