@via-profit/ability 3.6.2 → 3.6.5

package/dist/index.d.ts

@@ -218,14 +218,14 @@ type AbilityExplainConfig = {
     readonly type: AbilityExplainType;
     readonly name: string;
     readonly match: AbilityMatchType;
-    readonly debugInfo?: boolean;
+    readonly debugInfo?: string;
 };
 declare class AbilityExplain {
     readonly type: AbilityExplainType;
     readonly children: AbilityExplain[];
     readonly name: string;
     readonly match: AbilityMatchType;
-    readonly debugInfo?: boolean;
+    readonly debugInfo?: string;
     constructor(config: AbilityExplainConfig, children?: AbilityExplain[]);
     toString(indentPrefix?: string, isLast?: boolean): string;
 }
@@ -396,10 +396,40 @@ declare abstract class AbilityStrategy<Resource extends ResourceObject = Record<
     readonly policies: readonly AbilityPolicy<Resource, Environment>[];
     private readonly matched;
     constructor(policies: readonly AbilityPolicy<Resource, Environment>[]);
+    /**
+     * Executes the strategy’s decision logic and returns the final policy effect
+     * (permit or deny).
+     *
+     * Each concrete strategy must implement its own evaluation rules:
+     * - how matched policies are interpreted,
+     * - how priority, order, or overrides are applied,
+     * - and how the final effect is determined.
+     *
+     * The implementation must also record the policy that actually determined
+     * the outcome (if any), so that decisivePolicy() can later expose it.
+     */
     abstract evaluate(): AbilityPolicyEffectType;
+    /**
+     * Returns the policy that directly determined the final decision of the strategy.
+     *
+     * This is:
+     * - the specific policy chosen by the strategy’s evaluation rules, or
+     * - null if the decision was made by default (e.g., no matched policies,
+     *   or the strategy cannot identify a single decisive policy).
+     *
+     * This method performs no computation; it simply exposes the result stored
+     * during evaluate(), enabling explainability and debugging tools to show
+     * why a decision was made.
+     */
+    abstract decisivePolicy(): AbilityPolicy<Resource, Environment> | null;
     matchedPolicies(): readonly AbilityPolicy<Resource, Environment, string>[];
+    hasMatched(): boolean;
     protected firstMatched(): AbilityPolicy<Resource, Environment> | null;
     protected lastMatched(): AbilityPolicy<Resource, Environment> | null;
+    protected firstDenied(): AbilityPolicy<Resource, Environment> | null;
+    protected firstPermitted(): AbilityPolicy<Resource, Environment> | null;
+    protected getPermitPolicies(): AbilityPolicy<Resource, Environment, string>[];
+    protected getDenyPolicies(): AbilityPolicy<Resource, Environment, string>[];
     protected hasPermit(): boolean;
     protected hasDeny(): boolean;
     isAllowed(): boolean;
@@ -416,7 +446,9 @@ declare class AbilityResult<R extends ResourceObject = Record<string, unknown>,
      *
      * Useful for debugging, logging, or building UI tools that visualize permission logic.
      */
-    explain(): readonly AbilityExplain[];
+    explain(): string;
+    decisive(): AbilityPolicy<R, E, string> | null;
+    explainDecisive(): string | null;
     isAllowed: () => boolean;
     isDenied: () => boolean;
 }
@@ -659,7 +691,9 @@ declare function ability<R extends ResourceObject = Record<string, unknown>, E e
  *   Result: deny (because not all policies permitted)
  */
 declare class AllMustPermitStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    private _decisive;
     evaluate(): AbilityPolicyEffectType;
+    decisivePolicy(): AbilityPolicy<R, E, string> | null;
 }
 
 /**
@@ -680,7 +714,9 @@ declare class AllMustPermitStrategy<R extends ResourceObject, E extends Environm
  *   Result: permit (because at least one policy permitted)
  */
 declare class AnyPermitStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    private _decisive;
     evaluate(): AbilityPolicyEffectType;
+    decisivePolicy(): AbilityPolicy<R, E, string> | null;
 }
 
 /**
@@ -702,7 +738,9 @@ declare class AnyPermitStrategy<R extends ResourceObject, E extends EnvironmentO
  *   Result: deny (because deny overrides everything)
  */
 declare class DenyOverridesStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    private _decisive;
     evaluate(): AbilityPolicyEffectType;
+    decisivePolicy(): AbilityPolicy<R, E, string> | null;
 }
 
 /**
@@ -723,7 +761,9 @@ declare class DenyOverridesStrategy<R extends ResourceObject, E extends Environm
  *   Result: permit (P2 is the first applicable)
  */
 declare class FirstMatchStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    private _decisive;
     evaluate(): AbilityPolicyEffectType;
+    decisivePolicy(): AbilityPolicy<R, E, string> | null;
 }
 
 /**
@@ -743,7 +783,9 @@ declare class FirstMatchStrategy<R extends ResourceObject, E extends Environment
  *   Result: deny (more than one applicable policy)
  */
 declare class OnlyOneApplicableStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    private _decisive;
     evaluate(): AbilityPolicyEffectType;
+    decisivePolicy(): AbilityPolicy<R, E, string> | null;
 }
 
 /**
@@ -765,7 +807,9 @@ declare class OnlyOneApplicableStrategy<R extends ResourceObject, E extends Envi
  *   Result: permit (permit overrides deny)
  */
 declare class PermitOverridesStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    private _decisive;
     evaluate(): AbilityPolicyEffectType;
+    decisivePolicy(): AbilityPolicy<R, E, string> | null;
 }
 
 /**
@@ -785,7 +829,9 @@ declare class PermitOverridesStrategy<R extends ResourceObject, E extends Enviro
  *   Result: permit (P3 is the last applicable)
  */
 declare class SequentialLastMatchStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    private _decisive;
     evaluate(): AbilityPolicyEffectType;
+    decisivePolicy(): AbilityPolicy<R, E, string> | null;
 }
 
 /**
@@ -806,7 +852,9 @@ declare class SequentialLastMatchStrategy<R extends ResourceObject, E extends En
  *   Result: permit (P2 has higher priority)
  */
 declare class PriorityStrategy<R extends ResourceObject, E extends EnvironmentObject = Record<string, unknown>> extends AbilityStrategy<R, E> {
+    private _decisive;
     evaluate(): AbilityPolicyEffectType;
+    decisivePolicy(): AbilityPolicy<R, E, string> | null;
 }
 
 export { AbilityCompare, AbilityCondition, AbilityDSLLexer, AbilityDSLParser, AbilityDSLToken, AbilityError, AbilityExplain, AbilityExplainPolicy, AbilityExplainRule, AbilityExplainRuleSet, AbilityJSONParser, AbilityMatch, AbilityParserError, AbilityPolicy, AbilityPolicyEffect, AbilityResolver, AbilityResult, AbilityRule, AbilityRuleSet, AbilityStrategy, AbilityTypeGenerator, AllMustPermitStrategy, AnyPermitStrategy, DenyOverridesStrategy, FirstMatchStrategy, OnlyOneApplicableStrategy, PermitOverridesStrategy, PriorityStrategy, SequentialLastMatchStrategy, TokenTypes, ability, fromLiteral, isConditionEqual, isConditionNotEqual, toLiteral };

package/dist/index.js

@@ -1,5 +1,3 @@
-'use strict';
-
 function brand$4(code) {
     return code;
 }
@@ -151,24 +149,28 @@ class AbilityExplain {
     toString(indentPrefix = '', isLast = true) {
         const isMatch = this.match === AbilityMatch.match;
         const mark = isMatch ? `${colors.green}✓${colors.reset}` : `${colors.red}✗${colors.reset}`;
-        const label = this.type === 'policy'
-            ? `${colors.blue}POLICY${colors.reset}`
-            : this.type === 'ruleSet'
-                ? `${colors.yellow}RULESET${colors.reset}`
-                : `${colors.white}RULE${colors.reset}`;
+        let label;
+        switch (this.type) {
+            case 'policy':
+                label = `${colors.blue}POLICY${colors.reset}`;
+                break;
+            case 'ruleSet':
+                label = `${colors.yellow}RULESET${colors.reset}`;
+                break;
+            default:
+                label = `${colors.white}RULE${colors.reset}`;
+        }
         const branch = indentPrefix.length === 0
             ? ''
             : isLast
                 ? `${colors.gray}└─${colors.reset} `
                 : `${colors.gray}├─${colors.reset} `;
         let out = `${indentPrefix}${branch}${label} ${this.name} — ${mark}`;
-        if (this.debugInfo) {
+        if (this.debugInfo)
             out += ` ${colors.gray}(${this.debugInfo})${colors.reset}`;
-        }
         const nextIndent = indentPrefix + (isLast ? '   ' : `${colors.gray}│  ${colors.reset}`);
-        this.children.forEach((child, index) => {
-            const last = index === this.children.length - 1;
-            out += '\n' + child.toString(nextIndent, last);
+        this.children.forEach((child, idx) => {
+            out += '\n' + child.toString(nextIndent, idx === this.children.length - 1);
         });
         return out;
     }
@@ -217,9 +219,21 @@ class AbilityResult {
      * Useful for debugging, logging, or building UI tools that visualize permission logic.
      */
     explain() {
-        return this.strategy.policies.map(policy => {
-            return new AbilityExplainPolicy(policy);
-        });
+        return this.strategy.policies
+            .map(policy => {
+            return new AbilityExplainPolicy(policy).toString();
+        })
+            .join('\n');
+    }
+    decisive() {
+        return this.strategy.decisivePolicy();
+    }
+    explainDecisive() {
+        const policy = this.decisive();
+        if (!policy) {
+            return null;
+        }
+        return new AbilityExplainPolicy(policy).toString();
     }
     isAllowed = () => {
         return this.strategy.isAllowed();
@@ -309,24 +323,25 @@ class AbilityResolver {
             .toLowerCase(); // optional: make case-insensitive
     }
     static matchPermissions(policySegments, inputSegments) {
-        const maxLen = Math.max(policySegments.length, inputSegments.length);
-        for (let i = 0; i < maxLen; i++) {
+        let i = 0;
+        for (; i < policySegments.length; i++) {
             const pSeg = policySegments[i];
             const iSeg = inputSegments[i];
-            if (pSeg === undefined) {
-                return false;
-            }
+            // '*' — глобальный wildcard: матчим всё, что дальше
             if (pSeg === '*') {
-                continue; // '*'
+                return true;
             }
+            // input закончился раньше — mismatch
             if (iSeg === undefined) {
                 return false;
             }
+            // обычное сравнение
             if (pSeg !== iSeg) {
                 return false;
             }
         }
-        return true;
+        // Если политика закончилась, но input длиннее — match только если последний сегмент был '*'
+        return i === inputSegments.length;
     }
 }
 
@@ -2991,17 +3006,33 @@ class AbilityStrategy {
     matchedPolicies() {
         return this.matched;
     }
+    hasMatched() {
+        return this.matched.length > 0;
+    }
     firstMatched() {
-        return this.matched[0] ?? null;
+        return this.matchedPolicies()[0] ?? null;
     }
     lastMatched() {
-        return this.matched.length > 0 ? this.matched[this.matched.length - 1] : null;
+        const list = this.matchedPolicies();
+        return list.length > 0 ? list[list.length - 1] : null;
+    }
+    firstDenied() {
+        return this.getDenyPolicies()[0] ?? null;
+    }
+    firstPermitted() {
+        return this.getPermitPolicies()[0] ?? null;
+    }
+    getPermitPolicies() {
+        return this.matched.filter(p => p.effect === AbilityPolicyEffect.permit);
+    }
+    getDenyPolicies() {
+        return this.matched.filter(p => p.effect === AbilityPolicyEffect.deny);
     }
     hasPermit() {
-        return this.matched.some(p => p.effect === AbilityPolicyEffect.permit);
+        return this.getPermitPolicies().length > 0;
     }
     hasDeny() {
-        return this.matched.some(p => p.effect === AbilityPolicyEffect.deny);
+        return this.getDenyPolicies().length > 0;
     }
     isAllowed() {
         return this.evaluate() === AbilityPolicyEffect.permit;
@@ -3029,13 +3060,24 @@ class AbilityStrategy {
  *   Result: deny (because not all policies permitted)
  */
 class AllMustPermitStrategy extends AbilityStrategy {
+    _decisive = null;
     evaluate() {
-        const matched = this.matchedPolicies();
-        if (matched.length === 0) {
+        // 1. Нет совпавших политик → deny, но решающей политики нет
+        if (!this.hasMatched()) {
+            this._decisive = null;
+            return AbilityPolicyEffect.deny;
+        }
+        // 2. Если есть deny — она решающая
+        const deny = this.firstDenied();
+        if (deny) {
+            this._decisive = deny;
             return AbilityPolicyEffect.deny;
         }
-        const allPermit = matched.every(p => p.effect === AbilityPolicyEffect.permit);
-        return allPermit ? AbilityPolicyEffect.permit : AbilityPolicyEffect.deny;
+        this._decisive = this.firstPermitted();
+        return AbilityPolicyEffect.permit;
+    }
+    decisivePolicy() {
+        return this._decisive;
     }
 }
 
@@ -3057,8 +3099,20 @@ class AllMustPermitStrategy extends AbilityStrategy {
  *   Result: permit (because at least one policy permitted)
  */
 class AnyPermitStrategy extends AbilityStrategy {
+    _decisive = null;
     evaluate() {
-        return this.hasPermit() ? AbilityPolicyEffect.permit : AbilityPolicyEffect.deny;
+        // 1. Если есть permit — он решающий
+        const permit = this.firstPermitted();
+        if (permit) {
+            this._decisive = permit;
+            return AbilityPolicyEffect.permit;
+        }
+        // 2. Нет permit → deny по умолчанию
+        this._decisive = null;
+        return AbilityPolicyEffect.deny;
+    }
+    decisivePolicy() {
+        return this._decisive;
     }
 }
 
@@ -3081,15 +3135,27 @@ class AnyPermitStrategy extends AbilityStrategy {
  *   Result: deny (because deny overrides everything)
  */
 class DenyOverridesStrategy extends AbilityStrategy {
+    _decisive = null;
     evaluate() {
-        if (this.hasDeny()) {
+        // 1. Если есть deny — он решающий
+        const deny = this.firstDenied();
+        if (deny) {
+            this._decisive = deny;
             return AbilityPolicyEffect.deny;
         }
-        if (this.hasPermit()) {
+        // 2. Если есть permit — он решающий
+        const permit = this.firstPermitted();
+        if (permit) {
+            this._decisive = permit;
             return AbilityPolicyEffect.permit;
         }
+        // 3. Нет ни permit, ни deny → deny по умолчанию
+        this._decisive = null;
         return AbilityPolicyEffect.deny;
     }
+    decisivePolicy() {
+        return this._decisive;
+    }
 }
 
 /**
@@ -3110,9 +3176,20 @@ class DenyOverridesStrategy extends AbilityStrategy {
  *   Result: permit (P2 is the first applicable)
  */
 class FirstMatchStrategy extends AbilityStrategy {
+    _decisive = null;
     evaluate() {
         const first = this.firstMatched();
-        return first?.effect ?? AbilityPolicyEffect.deny;
+        // Если нет совпавших политик → deny по умолчанию
+        if (!first) {
+            this._decisive = null;
+            return AbilityPolicyEffect.deny;
+        }
+        // Первая совпавшая политика — решающая
+        this._decisive = first;
+        return first.effect;
+    }
+    decisivePolicy() {
+        return this._decisive;
     }
 }
 
@@ -3133,13 +3210,21 @@ class FirstMatchStrategy extends AbilityStrategy {
  *   Result: deny (more than one applicable policy)
  */
 class OnlyOneApplicableStrategy extends AbilityStrategy {
+    _decisive = null;
     evaluate() {
         const matched = this.matchedPolicies();
+        // 1. Ровно одна совпавшая политика → она решающая
         if (matched.length === 1) {
+            this._decisive = matched[0];
             return matched[0].effect;
         }
+        // 2. Иначе deny, решающей политики нет
+        this._decisive = null;
         return AbilityPolicyEffect.deny;
     }
+    decisivePolicy() {
+        return this._decisive;
+    }
 }
 
 /**
@@ -3161,15 +3246,27 @@ class OnlyOneApplicableStrategy extends AbilityStrategy {
  *   Result: permit (permit overrides deny)
  */
 class PermitOverridesStrategy extends AbilityStrategy {
+    _decisive = null;
     evaluate() {
-        if (this.hasPermit()) {
+        // 1. Если есть permit — он выигрывает
+        const permit = this.matchedPolicies().find(p => p.effect === AbilityPolicyEffect.permit);
+        if (permit) {
+            this._decisive = permit;
             return AbilityPolicyEffect.permit;
         }
-        if (this.hasDeny()) {
+        // 2. Если permit нет — ищем deny
+        const deny = this.matchedPolicies().find(p => p.effect === AbilityPolicyEffect.deny);
+        if (deny) {
+            this._decisive = deny;
             return AbilityPolicyEffect.deny;
         }
+        // 3. Нет ни permit, ни deny → deny по умолчанию
+        this._decisive = null;
         return AbilityPolicyEffect.deny;
     }
+    decisivePolicy() {
+        return this._decisive;
+    }
 }
 
 /**
@@ -3189,9 +3286,20 @@ class PermitOverridesStrategy extends AbilityStrategy {
  *   Result: permit (P3 is the last applicable)
  */
 class SequentialLastMatchStrategy extends AbilityStrategy {
+    _decisive = null;
     evaluate() {
         const last = this.lastMatched();
-        return last?.effect ?? AbilityPolicyEffect.deny;
+        // Нет совпавших политик → deny по умолчанию
+        if (!last) {
+            this._decisive = null;
+            return AbilityPolicyEffect.deny;
+        }
+        // Последняя совпавшая политика — решающая
+        this._decisive = last;
+        return last.effect;
+    }
+    decisivePolicy() {
+        return this._decisive;
     }
 }
 
@@ -3213,48 +3321,24 @@ class SequentialLastMatchStrategy extends AbilityStrategy {
  *   Result: permit (P2 has higher priority)
  */
 class PriorityStrategy extends AbilityStrategy {
+    _decisive = null;
     evaluate() {
         const matched = this.matchedPolicies();
+        // 1. Нет совпавших политик → deny, решающей политики нет
         if (matched.length === 0) {
+            this._decisive = null;
             return AbilityPolicyEffect.deny;
         }
+        // 2. Сортируем по приоритету (больший приоритет — выше)
         const sorted = [...matched].sort((a, b) => b.priority - a.priority);
-        return sorted[0].effect;
+        // 3. Самая приоритетная политика — решающая
+        const top = sorted[0];
+        this._decisive = top;
+        return top.effect;
+    }
+    decisivePolicy() {
+        return this._decisive;
     }
 }
 
-exports.AbilityCompare = AbilityCompare;
-exports.AbilityCondition = AbilityCondition;
-exports.AbilityDSLLexer = AbilityDSLLexer;
-exports.AbilityDSLParser = AbilityDSLParser;
-exports.AbilityDSLToken = AbilityDSLToken;
-exports.AbilityError = AbilityError;
-exports.AbilityExplain = AbilityExplain;
-exports.AbilityExplainPolicy = AbilityExplainPolicy;
-exports.AbilityExplainRule = AbilityExplainRule;
-exports.AbilityExplainRuleSet = AbilityExplainRuleSet;
-exports.AbilityJSONParser = AbilityJSONParser;
-exports.AbilityMatch = AbilityMatch;
-exports.AbilityParserError = AbilityParserError;
-exports.AbilityPolicy = AbilityPolicy;
-exports.AbilityPolicyEffect = AbilityPolicyEffect;
-exports.AbilityResolver = AbilityResolver;
-exports.AbilityResult = AbilityResult;
-exports.AbilityRule = AbilityRule;
-exports.AbilityRuleSet = AbilityRuleSet;
-exports.AbilityStrategy = AbilityStrategy;
-exports.AbilityTypeGenerator = AbilityTypeGenerator;
-exports.AllMustPermitStrategy = AllMustPermitStrategy;
-exports.AnyPermitStrategy = AnyPermitStrategy;
-exports.DenyOverridesStrategy = DenyOverridesStrategy;
-exports.FirstMatchStrategy = FirstMatchStrategy;
-exports.OnlyOneApplicableStrategy = OnlyOneApplicableStrategy;
-exports.PermitOverridesStrategy = PermitOverridesStrategy;
-exports.PriorityStrategy = PriorityStrategy;
-exports.SequentialLastMatchStrategy = SequentialLastMatchStrategy;
-exports.TokenTypes = TokenTypes;
-exports.ability = ability;
-exports.fromLiteral = fromLiteral;
-exports.isConditionEqual = isConditionEqual;
-exports.isConditionNotEqual = isConditionNotEqual;
-exports.toLiteral = toLiteral;
+export { AbilityCompare, AbilityCondition, AbilityDSLLexer, AbilityDSLParser, AbilityDSLToken, AbilityError, AbilityExplain, AbilityExplainPolicy, AbilityExplainRule, AbilityExplainRuleSet, AbilityJSONParser, AbilityMatch, AbilityParserError, AbilityPolicy, AbilityPolicyEffect, AbilityResolver, AbilityResult, AbilityRule, AbilityRuleSet, AbilityStrategy, AbilityTypeGenerator, AllMustPermitStrategy, AnyPermitStrategy, DenyOverridesStrategy, FirstMatchStrategy, OnlyOneApplicableStrategy, PermitOverridesStrategy, PriorityStrategy, SequentialLastMatchStrategy, TokenTypes, ability, fromLiteral, isConditionEqual, isConditionNotEqual, toLiteral };

package/package.json

@@ -1,14 +1,21 @@
 {
   "name": "@via-profit/ability",
   "support": "https://via-profit.ru",
-  "version": "3.6.2",
+  "version": "3.6.5",
   "description": "Via-Profit Ability service",
   "keywords": [
     "ability",
     "access",
     "via-profit"
   ],
-  "main": "./dist/index.js",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    "import": "./dist/index.js",
+    "require": "./dist/index.cjs"
+  },
+  "types": "./dist/index.d.ts",
   "engines": {
     "node": ">= 17.0.0",
     "npm": ">= 8.19.3"