@objectstack/lint 13.0.0 → 14.5.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,12 @@ 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 SECURITY_FLS_UNQUALIFIED_KEY = "security-fls-unqualified-key";
+var SECURITY_GRANT_EXPIRED_AT_AUTHORING = "security-grant-expired-at-authoring";
+var SECURITY_DELEGATION_MISSING_REASON = "security-delegation-missing-reason";
 var CANONICAL_OWD = ["private", "public_read", "public_read_write", "controlled_by_parent"];
 var OWD_ALIAS_FIX = {
   read: "public_read",
@@ -1319,7 +1406,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 +1427,26 @@ function labelHasRoleWord(label) {
   if (typeof label !== "string") return false;
   return /\brole(s)?\b/i.test(label);
 }
-function validateSecurityPosture(stack) {
+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, opts) {
   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;
@@ -1410,6 +1512,18 @@ function validateSecurityPosture(stack) {
     const psName = typeof ps.name === "string" ? ps.name : `(permission set ${i})`;
     const psPath = `permissions[${i}]`;
     const objectsMap = ps.objects && typeof ps.objects === "object" ? ps.objects : {};
+    const flsMap = ps.fields && typeof ps.fields === "object" ? ps.fields : {};
+    for (const flsKey of Object.keys(flsMap)) {
+      if (flsKey.includes(".")) continue;
+      findings.push({
+        severity: "error",
+        rule: SECURITY_FLS_UNQUALIFIED_KEY,
+        where: `permission set "${psName}"`,
+        path: `${psPath}.fields["${flsKey}"]`,
+        message: `field-permission key '${flsKey}' is not object-qualified \u2014 the runtime matches FLS keys by '<object>.<field>' prefix, so a bare key is silently IGNORED and the declared masking never enforces.`,
+        hint: `Qualify the key with its object, e.g. 'crm_opportunity.${flsKey}': { readable: true, editable: false }.`
+      });
+    }
     const wildcard = objectsMap["*"];
     if (wildcard && (wildcard.viewAllRecords === true || wildcard.modifyAllRecords === true)) {
       findings.push({
@@ -1461,10 +1575,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 +1587,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 +1643,82 @@ 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.`
+        });
+      }
+    }
+  }
+  const GRANT_SEED_OBJECTS = /* @__PURE__ */ new Set(["sys_user_position", "sys_user_permission_set"]);
+  const nowMs = opts?.nowMs ?? Date.now();
+  for (const [i, seed] of asArray14(stack.data).entries()) {
+    const seedObject = typeof seed.object === "string" ? seed.object : "";
+    if (!GRANT_SEED_OBJECTS.has(seedObject)) continue;
+    const records = Array.isArray(seed.records) ? seed.records : [];
+    for (let j = 0; j < records.length; j++) {
+      const rec = records[j] ?? {};
+      const where = `seed "${seedObject}" record #${j}`;
+      const until = rec.valid_until;
+      if (until != null && until !== "") {
+        const ms = typeof until === "number" ? until < 1e12 ? until * 1e3 : until : until instanceof Date ? until.getTime() : typeof until === "string" ? Date.parse(until) : Number.NaN;
+        if (Number.isNaN(ms) || ms <= nowMs) {
+          findings.push({
+            severity: "error",
+            rule: SECURITY_GRANT_EXPIRED_AT_AUTHORING,
+            where,
+            path: `data[${i}].records[${j}].valid_until`,
+            message: Number.isNaN(ms) ? `valid_until ${JSON.stringify(until)} is not a parseable timestamp \u2014 the resolver fails closed (ADR-0091 D2), so this grant will NEVER be active.` : `valid_until ${JSON.stringify(until)} is already in the past \u2014 this grant is expired at authoring time and will never resolve (ADR-0091 D2 filters it fail-closed).`,
+            hint: `Set valid_until to a future instant (ISO-8601 UTC), or drop the column for an unbounded grant. If the row is a historical record, it belongs in audit history, not seed data.`
+          });
+        }
+      }
+      const delegatedFrom = rec.delegated_from;
+      if (delegatedFrom != null && delegatedFrom !== "") {
+        const reason = rec.reason;
+        if (typeof reason !== "string" || reason.trim().length === 0) {
+          findings.push({
+            severity: "error",
+            rule: SECURITY_DELEGATION_MISSING_REASON,
+            where,
+            path: `data[${i}].records[${j}].reason`,
+            message: `delegation row (delegated_from = ${JSON.stringify(delegatedFrom)}) has no reason. ADR-0091 D3 requires a mandatory reason on every delegation for the dual audit trail (granted_by = writer, delegated_from = authority source, reason = why).`,
+            hint: `Add reason: 'vacation stand-in for \u5F20\u4E09, 2026-08-01..15' (free text, required).`
+          });
+        }
+      }
+    }
+  }
   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 +1729,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 +1806,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,7 +1820,11 @@ export {
   MEASURE_AGGREGATE_INCOHERENT,
   PAGE_SOURCE_CLASSNAME,
   SECURITY_ANCHOR_HIGH_PRIVILEGE,
+  SECURITY_BOOK_AUDIENCE_UNKNOWN_SET,
+  SECURITY_DELEGATION_MISSING_REASON,
   SECURITY_EXTERNAL_WIDER,
+  SECURITY_GRANT_EXPIRED_AT_AUTHORING,
+  SECURITY_MASTER_DETAIL_UNGRANTED,
   SECURITY_OWD_ALIAS,
   SECURITY_OWD_UNSET,
   SECURITY_PRIVATE_NO_READSCOPE,
@@ -1630,6 +1844,7 @@ export {
   WIDGET_MEASURE_UNKNOWN,
   buildAccessMatrix,
   diffAccessMatrix,
+  validateApprovalApprovers,
   validateCapabilityReferences,
   validateFormLayout,
   validateJsxPages,