Adjust priority of linting filters if proprocessor directives conditions are met

[piquark6046]

Any filters list has its own installation preference/ideal like that AdGuard filters lists are expected to be installed on AdGuard products and uBO's uAssets filters on uBlock Origin.
However, to partly/silently/fully support installation on a 3rd-party adblocker platform, each filters list can use proprocessor directives condition (!#if) that can override platform/syntax value of pre-existing AGLint config file.

However, current beta (4.0.0-beta.3) does not adjust priority of linting filters with any proprocessor directives condition.

For example, the attached screenshot shows that AGLint ignores !#if (ext_ublock) and follows platforms: adg_any. Therefore, I can see an error.

Screenshot

[scripthunter7]

Thank you for opening this issue! You’re right that platform handling in its current form does not cover many real-world cases. I’ve been thinking a lot about how this could be improved, and below is the best direction I’ve come up with so far. The idea has multiple layers.

1. Platform handling in config files

The first thing we need to clarify is how platforms should be specified in configuration files.

Right now there are two major weaknesses:

1. The current approach only allows you to list platforms freely, which can easily lead to “mixed” platform definitions.
2. If you keep multiple files in the same folder, you cannot define platform-specific configuration per file (e.g., having adguard-filter.txt and ublock-filter.txt in the same directory). This could be solved with a sub-config file (creating a folder, like adguard with a sub-config file and move adguard-filter.txt there), but its not always ideal.

Proposed solution

1. We should only allow platforms that belong to a single product at a time — e.g., adg_any or adg_os_any | adg_cb_any, but not adg_ext_any | ubo_ext_any, since that mixes two different products. This ensures that a file never ends up with any mixed-platform logic.
2. We must introduce a way to apply custom configurations for specific files. Similar to ESLint, this can be achieved by adding an overrides section:

Suppose you have a directory containing both adguard-filter.txt and ublock-filter.txt. You need to be able to assign different platforms to them. Something like this:

root: true
extends:
  - aglint:recommended
overrides:
  - files: ['ublock-filter.txt']
    platforms: ubo_any
    rules:
      some-rule: off
  - files: ['adguard-filter.txt']
    platforms: adg_any

The overrides mechanism allows you to define custom linter configurations for individual files or glob patterns.

2. Respecting special comments

This part is more complex. Currently, AGLint only respects special comments starting with the aglint- prefix. The previous section ensures that each file corresponds to a single product, and that becomes important when dealing with special comments.

Whenever a parsed rule is not compatible with the product used for filtering, AGLint should report an error.

Adblock Plus

As far as I know, ABP does not support preprocessor directives or hints. Therefore no special comments apply, and any incompatible elements should trigger an error. Or should we allow preprocessor directives for ABP as well? (Although in this case we should not consider the preprocessor comment as some syntax specific thing, but as a compiler/linter level thing (also). The point is that the responsibilities should be well defined.)

uBlock Origin

For uBO we must respect preprocessor directives. We need to validate that only platforms supported by uBO are used. The list of supported platforms is available here:
https://github.com/gorhill/uBlock/wiki/Static-filter-syntax#if-condition

Whenever we “enter” a conditional block, we temporarily override the platform defined in the config — but only within the limits of what uBO supports (same should happen for AdGuard).

We also need to detect invalid nested logic, for example:

!#if adguard_app_android
!#if adguard_app_windows
...
!#endif
!#endif

The inner condition can never be true inside the outer one, so this should produce an error.

Another problematic case is:

!#if ext_abp || adguard_app_android
...
!#endif

This again mixes platforms from different products, recreating the mixed-platform issue that the first chapter aims to eliminate. The solution for this scenario is described in section 3.

AdGuard

For AdGuard things become even more complex. In addition to preprocessor directives, AdGuard also supports hints. Therefore we need to account for:

• PLATFORM
• NOT_PLATFORM
• NOT_VALIDATE

NOT_VALIDATE is effectively equivalent to ! aglint-disable-next-line.

We should allow the user to control whether AGLint respects these special comments at all. This requires adding two options to the main config:

• respectPreprocessorDirectives
• respectHints

If the user sets these to false, AGLint should simply ignore all these comment-based mechanisms.

3. Consistency within a single rule

Besides checking the compatibility of individual elements (e.g., modifiers), we must ensure that a rule does not contain mixed logic inside its own structure. For example, if one modifier is only compatible with uBO and another only with AdGuard, that should trigger an error.

If multiple generic platforms are available within the scope (which can only happen inside preprocessor directives, thanks to earlier restrictions), then we must ensure that the rule remains compatible with at least one product. Otherwise, AGLint should suggest converting the rule using the rule converter, which handles mixed elements.

4. AGTree changes (later work)

Currently, AST nodes in rules contain a syntax property, which can take one of the following values: Common, AdGuard, uBlock, or AdblockPlus. However, this information is not always accurate.

Example 1: Incorrect fallback to Common

Consider the following rule:

foo.com##:matches-path(/foo) .foo

AGTree detects this as uBlock syntax. But if the user disables parsing of uBlock rules via configuration, the syntax property ends up being set to Common, which is incorrect. In reality, we do not know the syntax, because detection was intentionally skipped due to the disabled option. In this scenario, Unknown would be a far more appropriate syntax value.

Example 2: Preprocessor rules detected as Common

Another example:

!#if (adguard && !ext_abp)

This also ends up being parsed as Common syntax, even though this expression is valid either in AdGuard syntax or in uBlock syntax. It is therefore not truly “common” — it is ambiguous, and ideally should be marked with something like Unknown or a multi-syntax metadata value.

Related issue

I opened a related issue in AGTree to address this problem: AdguardTeam/tsurlfilter#178

---

So guys, this whole platform and compatibility topic is pretty complex, but we need to finalize it before the v4 stable release. What do you think about these ideas?

cc @AdguardTeam/filters-maintainers @slavaleleka @maximtop