@adguard/dnr-converter 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/README.md +62 -3
  2. package/dist/cli.cjs +51902 -47539
  3. package/dist/constants.js +4 -1
  4. package/dist/errors/conversion-errors/index.js +3 -2
  5. package/dist/errors/conversion-errors/unexpected-conversion-error.js +23 -0
  6. package/dist/errors/scan-errors.js +39 -0
  7. package/dist/errors/unavailable-sources-errors/unavailable-filter-source-error.js +10 -1
  8. package/dist/filter-converter/filter-converter.js +151 -6
  9. package/dist/index.js +5 -1
  10. package/dist/package.json.js +1 -1
  11. package/dist/rule/rule-badfilter.js +144 -55
  12. package/dist/rule/rule-validator.js +56 -6
  13. package/dist/rule/rule.js +95 -9
  14. package/dist/rule-converters/action-kind.js +121 -0
  15. package/dist/rule-converters/csp-condition-coverage.js +268 -0
  16. package/dist/rule-converters/csp-converter.js +132 -11
  17. package/dist/rule-converters/csp-rules-resolver.js +417 -0
  18. package/dist/rule-converters/regular-rule-converter.js +479 -129
  19. package/dist/rule-converters/rules-converter.js +75 -7
  20. package/dist/rule-converters/rules-grouper.js +5 -3
  21. package/dist/rules-scanner/rules-scanner.js +124 -56
  22. package/dist/ruleset/ruleset-with-source-map.js +5 -1
  23. package/dist/types/src/errors/conversion-errors/index.d.ts +7 -2
  24. package/dist/types/src/errors/conversion-errors/unexpected-conversion-error.d.ts +21 -0
  25. package/dist/types/src/errors/scan-errors.d.ts +38 -0
  26. package/dist/types/src/errors/unavailable-sources-errors/unavailable-filter-source-error.d.ts +9 -1
  27. package/dist/types/src/filter-converter/filter-converter-options.d.ts +18 -1
  28. package/dist/types/src/filter-converter/filter-converter.d.ts +83 -6
  29. package/dist/types/src/index.d.ts +7 -3
  30. package/dist/types/src/rule/rule-validator.d.ts +21 -0
  31. package/dist/types/src/rule/rule.d.ts +52 -2
  32. package/dist/types/src/rule-converters/csp-converter.d.ts +12 -0
  33. package/dist/types/src/ruleset/ruleset-with-source-map.d.ts +14 -0
  34. package/dist/utils/string.js +27 -1
  35. package/package.json +6 -6
  36. package/dist/rule/string-utils.js +0 -49
@@ -1,14 +1,18 @@
1
- import { InvalidDeclarativeRuleError } from '../errors/conversion-errors/invalid-declarative-rule-error.js';
1
+ import { isConversionError } from '../errors/conversion-errors/index.js';
2
2
  import { TooManyRegexpRulesError } from '../errors/limitation-errors/too-many-regexp-rules-error.js';
3
3
  import { TooManyRulesError } from '../errors/limitation-errors/too-many-rules-error.js';
4
4
  import { TooManyUnsafeRulesError } from '../errors/limitation-errors/too-many-unsafe-rules-error.js';
5
5
  import { UrlTransformRulesConverter } from '../grouped-rules-converters/url-transform-converter.js';
6
+ import { OPTION_NAMES } from '../rule/option-names.js';
6
7
  import { isSafeRule } from '../utils/is-safe-rule.js';
7
8
  import { Lazy } from '../utils/lazy.js';
8
9
  import { CspConverter } from './csp-converter.js';
10
+ import { CspRulesResolver } from './csp-rules-resolver.js';
9
11
  import { RegularRuleConverter } from './regular-rule-converter.js';
10
12
  import { RemoveHeaderConverter } from './remove-header-converter.js';
11
13
  import { RulesGroup, RulesGrouper } from './rules-grouper.js';
14
+ import { UnsupportedModifierError } from '../errors/conversion-errors/unsupported-modifier-error.js';
15
+ import { InvalidDeclarativeRuleError } from '../errors/conversion-errors/invalid-declarative-rule-error.js';
12
16
 
13
17
  /**
14
18
  * Class that converts list of {@link Rule} into list of {@link DeclarativeRule}.
@@ -29,6 +33,67 @@ import { RulesGroup, RulesGrouper } from './rules-grouper.js';
29
33
  * @returns Result object of {@link ConvertedRules}.
30
34
  */ static async convert(scannedFilters, options) {
31
35
  const filters = RulesConverter.applyBadFilter(scannedFilters);
36
+ return RulesConverter.convertGroupedFilters(filters, options);
37
+ }
38
+ /**
39
+ * Resolves CSP exceptions and converts the remaining CSP rules.
40
+ *
41
+ * Blocking rules which cannot be converted are excluded from resolution
42
+ * and reported once, as they fail the conversion pass anyway.
43
+ *
44
+ * @param scannedFilters Scanned filters containing CSP and `$badfilter` rules.
45
+ * @param options Options for conversion.
46
+ *
47
+ * @returns Converted CSP rules.
48
+ */ static async convertCspRules(scannedFilters, options) {
49
+ const filters = RulesConverter.applyBadFilter(scannedFilters);
50
+ const cspRules = filters.flatMap(([, groupedRules])=>groupedRules[RulesGroup.Csp]);
51
+ const blockingPreflightResults = await Promise.all(filters.map(async ([filterId, groupedRules])=>new CspConverter(options?.resourcesPath).convert(filterId, groupedRules[RulesGroup.Csp].filter((rule)=>!rule.allowlist), new Set())));
52
+ const blockingPreflightErrors = blockingPreflightResults.flatMap(({ errors })=>errors);
53
+ const invalidBlockingRules = new Set(blockingPreflightErrors.flatMap((error)=>isConversionError(error) ? [
54
+ error.rule
55
+ ] : []));
56
+ const invalidCspExceptions = new Map();
57
+ const validCspRules = cspRules.filter((rule)=>{
58
+ if (!rule.allowlist) {
59
+ return !invalidBlockingRules.has(rule);
60
+ }
61
+ const reason = CspRulesResolver.getUnprocessableReason(rule);
62
+ if (reason !== null) {
63
+ invalidCspExceptions.set(rule, new UnsupportedModifierError(reason, rule));
64
+ return false;
65
+ }
66
+ return true;
67
+ });
68
+ const { rules: resolvedCspRules, excludedRequestDomains, unsupportedExceptions } = CspRulesResolver.resolve(validCspRules);
69
+ const resolvedCspRulesSet = new Set(resolvedCspRules);
70
+ const resolvedFilters = filters.map(([filterId, groupedRules])=>[
71
+ filterId,
72
+ {
73
+ ...groupedRules,
74
+ [RulesGroup.Csp]: groupedRules[RulesGroup.Csp].filter((rule)=>resolvedCspRulesSet.has(rule))
75
+ }
76
+ ]);
77
+ const converted = await RulesConverter.convertGroupedFilters(resolvedFilters, options, excludedRequestDomains);
78
+ return {
79
+ ...converted,
80
+ errors: [
81
+ ...blockingPreflightErrors,
82
+ ...invalidCspExceptions.values(),
83
+ ...unsupportedExceptions.map((rule)=>new UnsupportedModifierError(CspRulesResolver.UNRESOLVABLE_EXCEPTION_MESSAGE, rule)),
84
+ ...converted.errors
85
+ ]
86
+ };
87
+ }
88
+ /**
89
+ * Converts already grouped filters.
90
+ *
91
+ * @param filters Filter IDs with grouped rules.
92
+ * @param options Options for conversion.
93
+ * @param excludedRequestDomains Domains excluded from resolved CSP rules.
94
+ *
95
+ * @returns Converted rules.
96
+ */ static async convertGroupedFilters(filters, options, excludedRequestDomains = new Map()) {
32
97
  let converted = {
33
98
  sourceMapValues: [],
34
99
  declarativeRules: [],
@@ -45,7 +110,7 @@ import { RulesGroup, RulesGrouper } from './rules-grouper.js';
45
110
  * after conversion.
46
111
  */ const uniqueIds = new Set();
47
112
  for (const [filterId, groupedRules] of filters){
48
- const { sourceMapValues, declarativeRules, errors } = await RulesConverter.convertRules(filterId, groupedRules, uniqueIds, options);
113
+ const { sourceMapValues, declarativeRules, errors } = await RulesConverter.convertRules(filterId, groupedRules, uniqueIds, options, excludedRequestDomains);
49
114
  converted.sourceMapValues = converted.sourceMapValues.concat(sourceMapValues);
50
115
  converted.declarativeRules = converted.declarativeRules.concat(declarativeRules);
51
116
  converted.errors = converted.errors.concat(errors);
@@ -66,9 +131,10 @@ import { RulesGroup, RulesGrouper } from './rules-grouper.js';
66
131
  * @param groupsRules {@link GroupedRules} to convert.
67
132
  * @param usedIds Set with already used IDs to exclude duplications in IDs.
68
133
  * @param options Options for conversion.
134
+ * @param excludedRequestDomains Domains excluded from resolved CSP rules.
69
135
  *
70
136
  * @returns Result object of {@link ConvertedRules}.
71
- */ static async convertRules(filterId, groupsRules, usedIds, options) {
137
+ */ static async convertRules(filterId, groupsRules, usedIds, options, excludedRequestDomains = new Map()) {
72
138
  const converted = {
73
139
  sourceMapValues: [],
74
140
  declarativeRules: [],
@@ -84,7 +150,8 @@ import { RulesGroup, RulesGrouper } from './rules-grouper.js';
84
150
  if (!rules || rules.length === 0) {
85
151
  return null;
86
152
  }
87
- const converter = new RulesConverter.CONVERTERS[key](options?.resourcesPath);
153
+ const Converter = RulesConverter.CONVERTERS[key];
154
+ const converter = key === RulesGroup.Csp ? new CspConverter(options?.resourcesPath, excludedRequestDomains) : new Converter(options?.resourcesPath);
88
155
  return converter.convert(filterId, rules, usedIds);
89
156
  }));
90
157
  for (const result of groupResults){
@@ -301,11 +368,12 @@ import { RulesGroup, RulesGrouper } from './rules-grouper.js';
301
368
  *
302
369
  * @returns Result tuple of {@link FiltersIdsWithGroupedRules}.
303
370
  */ static applyBadFilter(scannedFilters) {
304
- let allBadFilterRules = [];
371
+ // The scanner already collects `$badfilter` rules into the metadata,
372
+ // so use them directly instead of re-collecting from grouped rules.
373
+ const allBadFilterRules = scannedFilters.flatMap(({ badFilterRules })=>badFilterRules);
305
374
  // Group rules
306
375
  const filterIdsWithGroupedRules = scannedFilters.map(({ id, rules })=>{
307
376
  const rulesToProcess = RulesGrouper.groupRules(rules);
308
- allBadFilterRules = allBadFilterRules.concat(rulesToProcess[RulesGroup.BadFilter]);
309
377
  const tuple = [
310
378
  id,
311
379
  rulesToProcess
@@ -327,7 +395,7 @@ import { RulesGroup, RulesGrouper } from './rules-grouper.js';
327
395
  // Map because RulesGroup values are numbers
328
396
  const groups = Object.keys(filtered).map(Number);
329
397
  groups.forEach((key)=>{
330
- filtered[key] = filtered[key].filter(filterByBadFilterFn);
398
+ filtered[key] = filtered[key].filter((rule)=>!rule.isModifierEnabled(OPTION_NAMES.BADFILTER) && filterByBadFilterFn(rule));
331
399
  });
332
400
  // Clean up bad filters rules — they are not converted
333
401
  // to declarative rules, only used for negation above
@@ -35,15 +35,17 @@ import { OPTION_NAMES } from '../rule/option-names.js';
35
35
  *
36
36
  * @returns Rule group ({@link RulesGroup}).
37
37
  */ static getRuleGroup(rule) {
38
+ // Must be checked before the convertible groups: a `$badfilter` rule may
39
+ // also carry a convertible modifier and would otherwise be converted.
40
+ if (rule.isModifierEnabled(OPTION_NAMES.BADFILTER)) {
41
+ return 3;
42
+ }
38
43
  if (rule.isModifierEnabled(OPTION_NAMES.REMOVEHEADER)) {
39
44
  return 1;
40
45
  }
41
46
  if (rule.isModifierEnabled(OPTION_NAMES.CSP)) {
42
47
  return 2;
43
48
  }
44
- if (rule.isModifierEnabled(OPTION_NAMES.BADFILTER)) {
45
- return 3;
46
- }
47
49
  if (rule.isModifierEnabled(OPTION_NAMES.URLTRANSFORM)) {
48
50
  return 4;
49
51
  }
@@ -1,8 +1,10 @@
1
1
  import { RuleCategory } from '@adguard/agtree';
2
2
  import { FilterListParser } from '@adguard/agtree/parser';
3
3
  import { MaxScannedRulesError } from '../errors/limitation-errors/max-scanned-rules-error.js';
4
+ import { RuleScanError } from '../errors/scan-errors.js';
4
5
  import { OPTION_NAMES } from '../rule/option-names.js';
5
6
  import { Rule } from '../rule/rule.js';
7
+ import { copyString } from '../utils/string.js';
6
8
 
7
9
  /**
8
10
  * Class that responsible for scanning filter rules and converting them into {@link Rule}.
@@ -11,17 +13,10 @@ import { Rule } from '../rule/rule.js';
11
13
  * Scans the list of filters for network rules.
12
14
  *
13
15
  * @param filters List of {@link IFilter}.
14
- * @param filterFn If this function is specified, it will be applied to each
15
- * rule after it has been parsed and transformed. This function is needed
16
- * for example to apply `$badfilter`: to exclude negated rules from the array
17
- * of rules that will be returned.
18
- * @param maxScannedRules Maximum number of network rules to
19
- * scan, all other rules will be ignored. It will be applied to each filter
20
- * separately, not for cumulative scope of rules from all filters, because
21
- * it looks simpler and more predictable solution to prevent too long scan.
16
+ * @param options Scan options, see {@link ScanFiltersOptions}.
22
17
  *
23
18
  * @returns Result object of {@link ScannedFiltersWithErrors}.
24
- */ static async scanFilters(filters, filterFn, maxScannedRules) {
19
+ */ static async scanFilters(filters, options = {}) {
25
20
  const result = {
26
21
  errors: [],
27
22
  filters: []
@@ -29,7 +24,7 @@ import { Rule } from '../rule/rule.js';
29
24
  for(let i = 0; i < filters.length; i += 1){
30
25
  const filter = filters[i];
31
26
  // eslint-disable-next-line no-await-in-loop
32
- const { errors, rules } = await RulesScanner.scanRules(filter, filterFn, maxScannedRules);
27
+ const { errors, rules } = await RulesScanner.scanRules(filter, options);
33
28
  const badFilterRules = rules.filter(RulesScanner.isBadFilterRule);
34
29
  result.errors = result.errors.concat(errors);
35
30
  result.filters.push({
@@ -45,65 +40,136 @@ import { Rule } from '../rule/rule.js';
45
40
  * and tries to convert each line into {@link Rule}.
46
41
  *
47
42
  * @param filter From which filter the rules should be scanned.
48
- * @param filterFn If this function is specified, it will be applied to each
49
- * rule after it has been parsed and transformed. This function is needed
50
- * for example to apply `$badfilter`: to exclude negated rules from the array
51
- * of rules that will be returned.
52
- * @param maxScannedRules Maximum number of network rules to
53
- * scan, all other rules will be ignored and an error {@link MaxScannedRulesError}
54
- * will be added to the list of result errors.
43
+ * @param options Scan options, see {@link ScanFiltersOptions}.
55
44
  *
56
45
  * @returns Result object of {@link ScannedRulesWithErrors}.
57
- */ static async scanRules(filter, filterFn, maxScannedRules) {
58
- const id = filter.getId();
46
+ */ static async scanRules(filter, options) {
47
+ const filterId = filter.getId();
59
48
  const content = await filter.getContent();
60
- // Parse filter content into AST
61
- const ast = FilterListParser.parse(content, RulesScanner.PARSER_OPTIONS);
62
- // Build result object
63
- let scannedRulesCount = 0;
49
+ const segments = RulesScanner.getSegments(content, options.lineSelector);
64
50
  const result = {
65
51
  errors: [],
66
52
  rules: []
67
53
  };
68
- for(let i = 0; i < ast.children.length; i += 1){
69
- /**
70
- * We use `!` because location info and raw rule is always included in our parser options.
71
- *
72
- * @see {@link RulesScanner.PARSER_OPTIONS}
73
- */ const node = ast.children[i];
74
- const index = node.start;
54
+ for (const segment of segments){
55
+ const isLimitReached = RulesScanner.parseSegment(result, filterId, segment, options.filterFn, options.maxScannedRules, options.skipErrorLineSelector);
56
+ if (isLimitReached) {
57
+ break;
58
+ }
59
+ }
60
+ return result;
61
+ }
62
+ /**
63
+ * Splits the filter content into segments to parse.
64
+ *
65
+ * Without a selector the whole content is parsed as a single segment,
66
+ * otherwise only lines matching the selector are returned.
67
+ *
68
+ * @param content Filter list content.
69
+ * @param lineSelector If this function is specified, only lines matching it
70
+ * are selected.
71
+ *
72
+ * @returns Segments to parse.
73
+ */ static getSegments(content, lineSelector) {
74
+ if (!lineSelector) {
75
+ return [
76
+ {
77
+ text: content,
78
+ offset: 0
79
+ }
80
+ ];
81
+ }
82
+ const segments = [];
83
+ let offset = 0;
84
+ for (const line of content.split(RulesScanner.LINE_BREAK)){
85
+ if (lineSelector(line)) {
86
+ // The line is a slice of the whole content and keeps it alive,
87
+ // so it is copied before it is stored.
88
+ segments.push({
89
+ text: copyString(line),
90
+ offset
91
+ });
92
+ }
93
+ offset += line.length + RulesScanner.LINE_BREAK.length;
94
+ }
95
+ return segments;
96
+ }
97
+ /**
98
+ * Parses a segment of the filter content and appends network rules and
99
+ * errors to the scan result.
100
+ *
101
+ * Location info and raw rule text are always present in
102
+ * {@link RulesScanner.PARSER_OPTIONS}, so they are used without additional
103
+ * checks.
104
+ *
105
+ * @param result Scan result to append to.
106
+ * @param filterId Id of the filter the segment belongs to.
107
+ * @param segment Segment of the filter content.
108
+ * @param filterFn If this function is specified, it will be applied to each
109
+ * parsed rule.
110
+ * @param maxScannedRules Maximum number of rules to scan, `undefined` if
111
+ * there is no limit.
112
+ * @param skipErrorLineSelector If this function is specified, parse errors
113
+ * of lines matching it are not reported.
114
+ *
115
+ * @returns Whether the limit of scanned rules has been reached.
116
+ */ static parseSegment(result, filterId, segment, filterFn, maxScannedRules, skipErrorLineSelector) {
117
+ const ast = FilterListParser.parse(segment.text, RulesScanner.PARSER_OPTIONS);
118
+ for (const node of ast.children){
119
+ const index = segment.offset + node.start;
75
120
  const raw = node.raws.text;
121
+ const isErrorSkipped = skipErrorLineSelector !== undefined && skipErrorLineSelector(raw);
76
122
  if (node.category === RuleCategory.Invalid) {
123
+ if (isErrorSkipped) {
124
+ continue;
125
+ }
77
126
  const { name, message } = node.error;
78
- const msg = `[${name}] ${message}: filter id - ${id}, line index - ${index}, line - ${raw}`;
79
- result.errors.push(new Error(msg));
127
+ const msg = `[${name}] ${message}: filter id - ${filterId}, ` + `line index - ${index}, line - ${raw}`;
128
+ result.errors.push(new RuleScanError(msg, filterId, index));
80
129
  continue;
81
130
  }
82
131
  try {
83
- const rules = Rule.parseFromNode(id, index, node);
132
+ const rules = Rule.parseFromNode(filterId, index, node);
84
133
  const filteredRules = filterFn ? rules.filter(filterFn) : rules;
85
134
  result.rules.push(...filteredRules);
86
- scannedRulesCount += filteredRules.length;
87
- if (maxScannedRules !== undefined && scannedRulesCount >= maxScannedRules) {
88
- const lastRuleLineIndex = rules[rules.length - 1].index;
89
- // This error needed for future improvements, for example
90
- // to show in the UI which rules were skipped.
91
- const msg = `Maximum number of scanned network rules reached at line index ${lastRuleLineIndex}.`;
92
- result.errors.push(new MaxScannedRulesError(msg, lastRuleLineIndex));
93
- break;
135
+ if (maxScannedRules !== undefined && result.rules.length >= maxScannedRules) {
136
+ const lastRuleIndex = rules[rules.length - 1].index;
137
+ result.errors.push(RulesScanner.createLimitReachedError(lastRuleIndex));
138
+ return true;
94
139
  }
95
- } catch (e) {
96
- if (e instanceof Error) {
97
- result.errors.push(e);
98
- } else {
99
- // eslint-disable-next-line max-len
100
- const msg = `Unknown error during creating network rule from raw string: filter id - ${id}, line index - ${index}, line - ${raw}`;
101
- result.errors.push(new Error(msg));
140
+ } catch (error) {
141
+ if (!isErrorSkipped) {
142
+ result.errors.push(RulesScanner.createRuleParseError(error, filterId, index, raw));
102
143
  }
103
- continue;
104
144
  }
105
145
  }
106
- return result;
146
+ return false;
147
+ }
148
+ /**
149
+ * Creates an error for a network rule which cannot be parsed.
150
+ *
151
+ * @param error Error thrown during rule creation.
152
+ * @param filterId Id of the filter the rule belongs to.
153
+ * @param index Index of the rule in the filter list.
154
+ * @param raw Raw text of the rule.
155
+ *
156
+ * @returns Error to report.
157
+ */ static createRuleParseError(error, filterId, index, raw) {
158
+ const message = error instanceof Error ? error.message : 'Unknown error during creating network rule from raw string: ' + `filter id - ${filterId}, line index - ${index}, line - ${raw}`;
159
+ return new RuleScanError(message, filterId, index, error);
160
+ }
161
+ /**
162
+ * Creates a limitation error for a filter whose scan limit has been reached.
163
+ *
164
+ * The error is reported to make the skipped rules visible, for example in
165
+ * the UI.
166
+ *
167
+ * @param lastRuleIndex Index of the last scanned rule.
168
+ *
169
+ * @returns Limitation error to report.
170
+ */ static createLimitReachedError(lastRuleIndex) {
171
+ const msg = 'Maximum number of scanned network rules reached at line index ' + `${lastRuleIndex}.`;
172
+ return new MaxScannedRulesError(msg, lastRuleIndex);
107
173
  }
108
174
  /**
109
175
  * Checks whether the given rule is a bad filter rule.
@@ -117,20 +183,22 @@ import { Rule } from '../rule/rule.js';
117
183
  }
118
184
  /**
119
185
  * Parser options for filter scanning.
186
+ *
187
+ * The parser is tolerant, so all errors are collected in the result instead
188
+ * of being thrown. Location info is required for source mapping, raw text —
189
+ * for error reporting. Rules of all syntaxes are parsed, while comments and
190
+ * host rules are ignored.
120
191
  */ RulesScanner.PARSER_OPTIONS = {
121
- // We don't want parser to throw errors, so we can collect them all in the result object
122
192
  tolerant: true,
123
- // Location info is needed for source mapping
124
193
  isLocIncluded: true,
125
- // All syntaxes (abp, ubo) should be parsed
126
194
  parseAbpSpecificRules: true,
127
195
  parseUboSpecificRules: true,
128
- // Raw text is needed for error reporting
129
196
  includeRaws: true,
130
- // We don't need to process comments
131
197
  ignoreComments: true,
132
- // We only need to process network rules
133
198
  parseHostRules: false
134
199
  };
200
+ /**
201
+ * Line separator in filter lists.
202
+ */ RulesScanner.LINE_BREAK = '\n';
135
203
 
136
204
  export { RulesScanner };
@@ -150,6 +150,10 @@ import { DeclarativeRuleValidator } from '../declarative-rule/declarative-rule.j
150
150
  throw new UnavailableRulesetSourceError(msg, id, e);
151
151
  }
152
152
  }
153
+ /** @inheritdoc */ async getSourceRuleIndexes(declarativeRuleId) {
154
+ await this.loadContent();
155
+ return this.sourceMap?.getByDeclarativeRuleId(declarativeRuleId) ?? [];
156
+ }
153
157
  /** @inheritdoc */ getBadFilterRules() {
154
158
  return this.badFilterRules;
155
159
  }
@@ -359,7 +363,7 @@ import { DeclarativeRuleValidator } from '../declarative-rule/declarative-rule.j
359
363
  // and stored in the `unsafeRules` array (metadata).
360
364
  safeRulesCount: this.safeRulesCount,
361
365
  rulesetHashMapRaw: this.rulesHashMap.serialize(),
362
- badFilterRulesRaw: this.badFilterRules.map((r)=>r.getText()),
366
+ badFilterRulesRaw: this.badFilterRules.map((r)=>r.originalText),
363
367
  unsafeRules
364
368
  };
365
369
  }
@@ -1,19 +1,24 @@
1
1
  import { EmptyDomainsError } from './empty-domains-error.js';
2
2
  import { EmptyResourcesError } from './empty-resources-error.js';
3
3
  import { InvalidDeclarativeRuleError } from './invalid-declarative-rule-error.js';
4
+ import { UnexpectedConversionError } from './unexpected-conversion-error.js';
4
5
  import { UnsupportedModifierError } from './unsupported-modifier-error.js';
5
6
  import { UnsupportedRegexpError } from './unsupported-regexp-error.js';
6
7
 
7
8
  /**
8
9
  * Union type of all conversion errors.
9
10
  *
11
+ * Every error of this union describes a source rule which could not be
12
+ * converted, so the rule is always available via the `rule` field.
13
+ *
10
14
  * @see {@link EmptyDomainsError}
11
15
  * @see {@link EmptyResourcesError}
12
16
  * @see {@link InvalidDeclarativeRuleError}
17
+ * @see {@link UnexpectedConversionError}
13
18
  * @see {@link UnsupportedModifierError}
14
19
  * @see {@link UnsupportedRegexpError}
15
20
  */
16
- type ConversionError = EmptyDomainsError | EmptyResourcesError | InvalidDeclarativeRuleError | UnsupportedModifierError | UnsupportedRegexpError;
21
+ type ConversionError = EmptyDomainsError | EmptyResourcesError | InvalidDeclarativeRuleError | UnexpectedConversionError | UnsupportedModifierError | UnsupportedRegexpError;
17
22
  /**
18
23
  * Type guard for {@link ConversionError}.
19
24
  *
@@ -23,5 +28,5 @@ type ConversionError = EmptyDomainsError | EmptyResourcesError | InvalidDeclarat
23
28
  */
24
29
  declare function isConversionError(error: unknown): error is ConversionError;
25
30
 
26
- export { EmptyDomainsError, EmptyResourcesError, InvalidDeclarativeRuleError, UnsupportedModifierError, UnsupportedRegexpError, isConversionError };
31
+ export { EmptyDomainsError, EmptyResourcesError, InvalidDeclarativeRuleError, UnexpectedConversionError, UnsupportedModifierError, UnsupportedRegexpError, isConversionError };
27
32
  export type { ConversionError };
@@ -0,0 +1,21 @@
1
+ import { Rule } from '../../rule/rule.js';
2
+
3
+ /**
4
+ * Describes an error of a rule which failed with an unexpected error.
5
+ */
6
+ declare class UnexpectedConversionError extends Error {
7
+ /**
8
+ * {@link Rule} related to this error.
9
+ */
10
+ rule: Rule;
11
+ /**
12
+ * Describes an error of a rule which failed with an unexpected error.
13
+ *
14
+ * @param message Message of error.
15
+ * @param rule {@link Rule}.
16
+ * @param cause Captured error.
17
+ */
18
+ constructor(message: string, rule: Rule, cause: unknown);
19
+ }
20
+
21
+ export { UnexpectedConversionError };
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Describes an error of a rule which could not be parsed or validated while
3
+ * scanning.
4
+ *
5
+ * Unlike a conversion error, such a rule is not available as a parsed rule, so
6
+ * the error keeps the filter id and the line index instead of the rule itself.
7
+ */
8
+ declare class RuleScanError extends Error {
9
+ /**
10
+ * Id of the filter the rule belongs to.
11
+ */
12
+ filterId: number;
13
+ /**
14
+ * Character offset of the rule in the filter content, the same value as
15
+ * `Rule.index`.
16
+ */
17
+ offset: number;
18
+ /**
19
+ * Describes an error of a rule which could not be parsed or validated
20
+ * while scanning.
21
+ *
22
+ * @param message Message of error.
23
+ * @param filterId Id of the filter the rule belongs to.
24
+ * @param offset Character offset of the rule in the filter content.
25
+ * @param cause Captured error.
26
+ */
27
+ constructor(message: string, filterId: number, offset: number, cause?: unknown);
28
+ }
29
+ /**
30
+ * Type guard for {@link RuleScanError}.
31
+ *
32
+ * @param error The error to check.
33
+ *
34
+ * @returns `true` if the error is a {@link RuleScanError}, `false` otherwise.
35
+ */
36
+ declare function isRuleScanError(error: unknown): error is RuleScanError;
37
+
38
+ export { RuleScanError, isRuleScanError };
@@ -15,5 +15,13 @@ declare class UnavailableFilterSourceError extends Error {
15
15
  */
16
16
  constructor(message: string, filterId: number, cause?: Error);
17
17
  }
18
+ /**
19
+ * Type guard for {@link UnavailableFilterSourceError}.
20
+ *
21
+ * @param error The error to check.
22
+ *
23
+ * @returns `true` if the error is a {@link UnavailableFilterSourceError}.
24
+ */
25
+ declare function isUnavailableFilterSourceError(error: unknown): error is UnavailableFilterSourceError;
18
26
 
19
- export { UnavailableFilterSourceError };
27
+ export { UnavailableFilterSourceError, isUnavailableFilterSourceError };
@@ -67,7 +67,24 @@ interface SourceMapConverterOptions extends BaseFilterConverterOptions {
67
67
  * Only valid in source-map mode (enforced by the discriminated union).
68
68
  */
69
69
  badFilterRules?: Rule[];
70
+ /**
71
+ * Excludes CSP rules from regular conversion when they are rebuilt globally.
72
+ *
73
+ * The caller must run `convertCspRules()` afterwards: this pass drops such
74
+ * rules together with their parse errors, because the CSP pass reports them.
75
+ *
76
+ * @default false
77
+ */
78
+ excludeCspRules?: boolean;
70
79
  }
80
+ /**
81
+ * Options for callers that compute `withSourceMap` at runtime (e.g. from a
82
+ * config flag typed as `boolean`). Mirrors {@link SourceMapConverterOptions}
83
+ * with a widened flag, so source-map-only options stay in sync with it.
84
+ */
85
+ type ComputedWithSourceMapOptions = Omit<SourceMapConverterOptions, 'withSourceMap'> & {
86
+ withSourceMap: boolean;
87
+ };
71
88
  /**
72
89
  * Interface that represents options for the converter.
73
90
  *
@@ -78,4 +95,4 @@ interface SourceMapConverterOptions extends BaseFilterConverterOptions {
78
95
  */
79
96
  type FilterConverterOptions = SimpleConverterOptions | SourceMapConverterOptions;
80
97
 
81
- export type { BaseFilterConverterOptions, FilterConverterOptions, SimpleConverterOptions, SourceMapConverterOptions };
98
+ export type { BaseFilterConverterOptions, ComputedWithSourceMapOptions, FilterConverterOptions, SimpleConverterOptions, SourceMapConverterOptions };