@via-profit/ability 3.6.1 → 3.6.4

package/dist/index.d.ts

@@ -218,14 +218,16 @@ type AbilityExplainConfig = {
     readonly type: AbilityExplainType;
     readonly name: string;
     readonly match: AbilityMatchType;
+    readonly debugInfo?: string;
 };
 declare class AbilityExplain {
     readonly type: AbilityExplainType;
     readonly children: AbilityExplain[];
     readonly name: string;
     readonly match: AbilityMatchType;
+    readonly debugInfo?: string;
     constructor(config: AbilityExplainConfig, children?: AbilityExplain[]);
-    toString(indent?: number): string;
+    toString(indentPrefix?: string, isLast?: boolean): string;
 }
 declare class AbilityExplainRule extends AbilityExplain {
     constructor(rule: AbilityRule);
@@ -394,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;
@@ -414,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;
 }
@@ -551,6 +585,7 @@ declare class AbilityDSLParser<R extends ResourceObject = Record<string, unknown
     private takeAnnotations;
     private isStartOfPolicy;
     private isStartOfGroup;
+    private isStartOfRule;
     private isStartOfExcept;
     private isStartOfAlias;
 }
@@ -656,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;
 }
 
 /**
@@ -677,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;
 }
 
 /**
@@ -699,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;
 }
 
 /**
@@ -720,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;
 }
 
 /**
@@ -740,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;
 }
 
 /**
@@ -762,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;
 }
 
 /**
@@ -782,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;
 }
 
 /**
@@ -803,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

@@ -126,27 +126,53 @@ const AbilityMatch = {
     disabled: brand$2('disabled'),
 };
 
+const colors = {
+    reset: '\x1b[0m',
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    blue: '\x1b[34m',
+    yellow: '\x1b[33m',
+    white: '\x1b[37m',
+    gray: '\x1b[90m',
+};
 class AbilityExplain {
     type;
     children;
     name;
     match;
+    debugInfo;
     constructor(config, children = []) {
         this.type = config.type;
         this.children = children;
         this.name = config.name;
         this.match = config.match;
-    }
-    toString(indent = 0) {
-        const pad = ' '.repeat(indent);
-        const mark = this.match === AbilityMatch.match ? '✓' : '✗';
-        let out = '';
-        if (this.type === 'policy') {
-            out += '\n';
+        this.debugInfo = config.debugInfo;
+    }
+    toString(indentPrefix = '', isLast = true) {
+        const isMatch = this.match === AbilityMatch.match;
+        const mark = isMatch ? `${colors.green}✓${colors.reset}` : `${colors.red}✗${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}`;
         }
-        out += `${pad}${mark} ${this.type} «${this.name}» is ${this.match}`;
-        this.children.forEach(child => {
-            out += '\n' + child.toString(indent + 1);
+        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)
+            out += ` ${colors.gray}(${this.debugInfo})${colors.reset}`;
+        const nextIndent = indentPrefix + (isLast ? '   ' : `${colors.gray}│  ${colors.reset}`);
+        this.children.forEach((child, idx) => {
+            out += '\n' + child.toString(nextIndent, idx === this.children.length - 1);
         });
         return out;
     }
@@ -195,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();
@@ -287,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;
     }
 }
 
@@ -1500,32 +1539,32 @@ class AbilityJSONParser {
         return {
             id: rule.id,
             name: rule.name,
+            disabled: rule.disabled,
             subject: rule.subject,
             resource: rule.resource,
             condition: rule.condition,
-            disabled: rule.disabled,
         };
     }
     static ruleSetToJSON(ruleSet) {
         return {
             id: ruleSet.id.toString(),
             name: ruleSet.name.toString(),
+            disabled: ruleSet.disabled,
             compareMethod: ruleSet.compareMethod,
             rules: ruleSet.rules.map(rule => AbilityJSONParser.ruleToJSON(rule)),
-            disabled: ruleSet.disabled,
         };
     }
     static policyToJSON(policy) {
         return {
             id: policy.id.toString(),
             name: policy.name.toString(),
-            compareMethod: policy.compareMethod,
-            ruleSet: policy.ruleSet.map(ruleSet => AbilityJSONParser.ruleSetToJSON(ruleSet)),
+            disabled: policy.disabled,
+            priority: policy.priority,
             permission: policy.permission,
             effect: policy.effect,
-            priority: policy.priority,
-            disabled: policy.disabled,
+            compareMethod: policy.compareMethod,
             tags: policy.tags,
+            ruleSet: policy.ruleSet.map(ruleSet => AbilityJSONParser.ruleSetToJSON(ruleSet)),
         };
     }
     static toJSON(policies) {
@@ -2313,28 +2352,34 @@ class AbilityDSLParser {
      */
     parseRuleSets(policyCompareMethod) {
         const sets = [];
+        this.consumeLeadingComments();
+        this.consumeLeadingAnnotations();
         while (!this.stream.eof() && !this.isStartOfPolicy()) {
-            this.consumeLeadingComments();
-            this.consumeLeadingAnnotations();
-            // Если начинается новая except группа — парсим её
+            // maybe except ruleSet
             if (this.isStartOfExcept()) {
                 sets.push(this.parseExceptGroup(policyCompareMethod));
                 continue;
             }
-            // Если начинается новая группа — парсим её
+            // maybe ruleSet
             if (this.isStartOfGroup()) {
                 sets.push(this.parseGroup());
                 continue;
             }
-            const annotation = this.takeAnnotations('ruleSet');
+            // implicit ruleSet
+            // if (!this.isStartOfRule()) {
+            //   this.consumeLeadingComments();
+            //   this.consumeLeadingAnnotations();
+            // }
+            // is implicit group
+            // const annotation = this.takeAnnotations('ruleSet');
             const group = new AbilityRuleSet({
-                id: annotation.id?.value || null,
+                // id: annotation.id?.value || null,
                 compareMethod: policyCompareMethod,
-                name: annotation.name?.value ?? null,
-                description: annotation.description?.value || null,
-                disabled: annotation.disabled?.value ?? undefined,
+                // name: annotation.name?.value ?? null,
+                // description: annotation.description?.value || null,
+                // disabled: annotation.disabled?.value ?? undefined,
             });
-            // Читаем правила implicit-группы
+            // Read rules of implicit-группы
             while (!this.stream.eof()) {
                 this.consumeLeadingComments();
                 this.consumeLeadingAnnotations();
@@ -2935,6 +2980,11 @@ class AbilityDSLParser {
     isStartOfGroup() {
         return this.stream.check(TokenTypes.ALL) || this.stream.check(TokenTypes.ANY);
     }
+    isStartOfRule() {
+        return (this.stream.check(TokenTypes.IDENTIFIER) ||
+            this.stream.check(TokenTypes.ALWAYS) ||
+            this.stream.check(TokenTypes.NEVER));
+    }
     isStartOfExcept() {
         return this.stream.check(TokenTypes.EXCEPT);
     }
@@ -2958,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;
@@ -2996,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;
+        }
+        // 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;
     }
 }
 
@@ -3024,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;
     }
 }
 
@@ -3048,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;
+    }
 }
 
 /**
@@ -3077,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;
     }
 }
 
@@ -3100,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;
+    }
 }
 
 /**
@@ -3128,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;
+    }
 }
 
 /**
@@ -3156,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;
     }
 }
 
@@ -3180,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.1",
+  "version": "3.6.4",
   "description": "Via-Profit Ability service",
   "keywords": [
     "ability",