@via-profit/ability 3.6.2 → 3.6.4

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

@@ -151,24 +151,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 +221,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 +325,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 +3008,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 +3062,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;
         }
-        const allPermit = matched.every(p => p.effect === AbilityPolicyEffect.permit);
-        return allPermit ? AbilityPolicyEffect.permit : AbilityPolicyEffect.deny;
+        // 2. Если есть deny — она решающая
+        const deny = this.firstDenied();
+        if (deny) {
+            this._decisive = deny;
+            return AbilityPolicyEffect.deny;
+        }
+        this._decisive = this.firstPermitted();
+        return AbilityPolicyEffect.permit;
+    }
+    decisivePolicy() {
+        return this._decisive;
     }
 }
 
@@ -3057,8 +3101,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 +3137,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 +3178,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 +3212,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 +3248,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 +3288,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,13 +3323,23 @@ 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;
     }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@via-profit/ability",
   "support": "https://via-profit.ru",
-  "version": "3.6.2",
+  "version": "3.6.4",
   "description": "Via-Profit Ability service",
   "keywords": [
     "ability",