Skip to content

Commit 21c0b8b

Browse files
maximtopmaximtop
committed
add documentation
1 parent ba0d69e commit 21c0b8b

File tree

7 files changed

+88
-36
lines changed

7 files changed

+88
-36
lines changed

‎.eslintrc.js

+1
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ module.exports = {
6767
'no-underscore-dangle': 'off',
6868
'import/prefer-default-export': 'off',
6969
'@typescript-eslint/explicit-function-return-type': 'off',
70+
'@typescript-eslint/no-explicit-any': 'error',
7071
},
7172
'overrides': [
7273
{

‎package.json

+2-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@
66
"main": "scripts/build/build.js",
77
"scripts": {
88
"auto-build": "bash scripts/auto_build.sh",
9-
"lint": "eslint . --ext .js,.ts",
9+
"lint": "eslint . --ext .js,.ts && yarn check-types",
10+
"check-types": "tsc --noEmit --project tsconfig.json",
1011
"test": "jest .",
1112
"build": "node scripts/build/build.js",
1213
"build:patches": "node scripts/build/patches.js",

‎scripts/wildcard-domain-processor/__tests__/platforms-patcher.test.ts

+12-12
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,15 @@ import { expandWildcardsInRule } from '../wildcard-expander';
22

33
describe('platforms-patcher', () => {
44
describe('expandWildcardsInRule', () => {
5-
describe('patch cosmetic rules', () => {
5+
describe('expand wildcards in cosmetic rules', () => {
66
it('should expand wildcard', () => {
77
const rule = 'example.*##h1';
88
const wildcardDomains = { 'example.*': ['example.com', 'example.org'] };
99
const patchedRule = expandWildcardsInRule(rule, wildcardDomains);
1010
expect(patchedRule).toEqual('example.com,example.org##h1');
1111
});
1212

13-
it('should expand wildcard and not lose non wildcard', () => {
13+
it('should expand wildcard and retain non-wildcard domains', () => {
1414
const rule = 'example.*,test.com##h1';
1515
const wildcardDomains = { 'example.*': ['example.com', 'example.org'] };
1616
const patchedRule = expandWildcardsInRule(rule, wildcardDomains);
@@ -24,15 +24,16 @@ describe('platforms-patcher', () => {
2424
expect(patchedRule).toEqual('~example.com,~example.org##h1');
2525
});
2626

27-
it('should return null if wildcardDomains were empty', () => {
27+
it('should return null if wildcardDomains is empty', () => {
2828
const rule = 'example.*##h1';
2929
const wildcardDomains = { 'example.*': [] };
3030
const patchedRule = expandWildcardsInRule(rule, wildcardDomains);
3131
expect(patchedRule).toEqual(null);
3232
});
3333

34-
it('if has restricted and permitted domains, they destroy each other', () => {
34+
it('should handle conflicts between restricted and permitted domains', () => {
3535
const wildcardDomains = { 'example.*': ['example.com', 'example.org'] };
36+
3637
const ruleWithPermittedWildcard = 'example.*,~example.org##h1';
3738
const patchedRuleWithPermittedWildcard = expandWildcardsInRule(
3839
ruleWithPermittedWildcard,
@@ -48,11 +49,11 @@ describe('platforms-patcher', () => {
4849
expect(patchedRuleWithRestrictedWildcard).toEqual('~example.com##h1');
4950
});
5051

51-
// eslint-disable-next-line max-len
52-
it('returns null if after expanding wildcard and destroying permitted and restricted no domains left', () => {
52+
it('should return null if no domains are left after resolving conflicts', () => {
5353
const ruleWithPermittedWildcard = 'example.*,~example.com##h1';
5454
const ruleWithRestrictedWildcard = '~example.*,example.com##h1';
5555
const wildcardDomains = { 'example.*': ['example.com'] };
56+
5657
const patchedRuleWithPermittedWildcard = expandWildcardsInRule(
5758
ruleWithPermittedWildcard,
5859
wildcardDomains,
@@ -74,7 +75,7 @@ describe('platforms-patcher', () => {
7475
});
7576
});
7677

77-
describe('patch network rules', () => {
78+
describe('expand wildcards in network rules', () => {
7879
it('should expand wildcard', () => {
7980
const wildcardDomains = { 'example.*': ['example.com', 'example.org'] };
8081

@@ -95,7 +96,7 @@ describe('platforms-patcher', () => {
9596
expect(expandedFromRule).toEqual('test$from=example.com|example.org');
9697
});
9798

98-
it('should expand wildcard and not lose non wildcard', () => {
99+
it('should expand wildcard and retain non-wildcard domains', () => {
99100
const rule = 'test$domain=example.*|test.com';
100101
const wildcardDomains = { 'example.*': ['example.com', 'example.org'] };
101102
const expandedRule = expandWildcardsInRule(rule, wildcardDomains);
@@ -109,14 +110,14 @@ describe('platforms-patcher', () => {
109110
expect(patchedRule).toEqual('test$domain=~example.com|~example.org');
110111
});
111112

112-
it('should return null if wildcardDomains were empty', () => {
113+
it('should return null if wildcardDomains is empty', () => {
113114
const rule = 'test$domain=example.*';
114115
const wildcardDomains = { 'example.*': [] };
115116
const patchedRule = expandWildcardsInRule(rule, wildcardDomains);
116117
expect(patchedRule).toEqual(null);
117118
});
118119

119-
it('if has restricted and permitted domains, they destroy each other', () => {
120+
it('should handle conflicts between restricted and permitted domains', () => {
120121
const wildcardDomains = { 'example.*': ['example.com', 'example.org'] };
121122
const ruleWithPermittedWildcard = 'test$domain=example.*|~example.org';
122123
const patchedRuleWithPermittedWildcard = expandWildcardsInRule(
@@ -133,8 +134,7 @@ describe('platforms-patcher', () => {
133134
expect(patchedRuleWithRestrictedWildcard).toEqual('test$domain=~example.com');
134135
});
135136

136-
// eslint-disable-next-line max-len
137-
it('returns null if after expanding wildcard and destroying permitted and restricted no domains left', () => {
137+
it('should return null if no domains are left after resolving conflicts', () => {
138138
const wildcardDomains = { 'example.*': ['example.com'] };
139139
const ruleWithPermittedWildcard = 'test$domain=example.*|~example.com';
140140
const patchedRuleWithPermittedWildcard = expandWildcardsInRule(

‎scripts/wildcard-domain-processor/utils.ts

+3-3
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ const ALLOW_TLD = new Set([
2626
* @param domain Domain to check
2727
* @returns True if domain ends with wildcard Tld
2828
*/
29-
const isDomainWithTldWildcard = (domain: string): boolean => {
29+
const isWildcardDomain = (domain: string): boolean => {
3030
return domain.endsWith('.*');
3131
};
3232

@@ -38,7 +38,7 @@ const isDomainWithTldWildcard = (domain: string): boolean => {
3838
*/
3939
function validDomain(domain: string): boolean {
4040
// If the domain ends with '.*', it is a wildcard domain and it is valid.
41-
if (isDomainWithTldWildcard(domain)) {
41+
if (isWildcardDomain(domain)) {
4242
return true;
4343
}
4444

@@ -71,5 +71,5 @@ function validDomain(domain: string): boolean {
7171
export const utils = {
7272
validDomain,
7373
unique,
74-
isDomainWithTldWildcard,
74+
isWildcardDomain,
7575
};

‎scripts/wildcard-domain-processor/wildcard-domain-processor.ts

+15-2
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ const getWildcardDomains = (filterContent: string): Set<string> => {
3939
const wildcardDomains = new Set<string>();
4040
for (const rule of rules) {
4141
const domains = getDomains(rule);
42-
const wildcardDomainsList = domains.filter((domain) => utils.isDomainWithTldWildcard(domain));
42+
const wildcardDomainsList = domains.filter((domain) => utils.isWildcardDomain(domain));
4343
wildcardDomainsList.forEach((domain) => wildcardDomains.add(domain));
4444
}
4545
return wildcardDomains;
@@ -53,6 +53,7 @@ export type WildcardDomainsWithTld = { [key: string]: string[] };
5353
/**
5454
* Supplements the wildcard domains with all possible TLDs.
5555
* @param wildcardDomains - The set of wildcard domains to supplement.
56+
* @returns A map of wildcard domains with all possible TLDs.
5657
*/
5758
function supplementWithTld(wildcardDomains: Set<string>): WildcardDomainsWithTld {
5859
const wildcardDomainsWithTld: WildcardDomainsWithTld = {};
@@ -66,12 +67,24 @@ function supplementWithTld(wildcardDomains: Set<string>): WildcardDomainsWithTld
6667
return wildcardDomainsWithTld;
6768
}
6869

69-
async function getAliveDomains(value: string[]): string[] {
70+
/**
71+
* Filters out dead domains from a list of domains.
72+
* @param value - The list of domains to filter.
73+
* @returns A list of alive domains.
74+
*/
75+
async function getAliveDomains(value: string[]): Promise<string[]> {
7076
const deadDomains = new Set(await findDeadDomains(value));
7177
const aliveDomains = value.filter((domain) => !deadDomains.has(domain));
7278
return aliveDomains;
7379
}
7480

81+
/**
82+
* Updates a JSON file with a key-value pair.
83+
* @param filename - The name of the JSON file.
84+
* @param key - The key to update in the JSON file.
85+
* @param value - The value to set for the key in the JSON file.
86+
* @returns A promise that resolves when the file is updated.
87+
*/
7588
async function updateJsonFile(filename: string, key: string, value: string[]): Promise<void> {
7689
const filePath = path.resolve(__dirname, filename);
7790
const json = await readFile(filePath);

‎scripts/wildcard-domain-processor/wildcard-expander.ts

+54-18
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,13 @@ import { WildcardDomainsWithTld } from './wildcard-domain-processor';
1212
import { DOMAIN_MODIFIERS } from './domain-extractor';
1313
import { utils } from './utils';
1414

15-
const expandWildcardInNetworkRuleAst = (
15+
/**
16+
* Expands wildcards in a network rule AST.
17+
* @param ast - The network rule AST to process.
18+
* @param wildcardDomains - A map of wildcard domains to their non-wildcard equivalents.
19+
* @returns The updated network rule AST with expanded wildcards, or null if no valid domains are left.
20+
*/
21+
const expandNetworkRulesWildcard = (
1622
ast: NetworkRule,
1723
wildcardDomains: WildcardDomainsWithTld,
1824
): NetworkRule | null => {
@@ -21,10 +27,8 @@ const expandWildcardInNetworkRuleAst = (
2127
}
2228

2329
const modifiers = ast.modifiers.children;
24-
2530
const newPermittedDomains = new Map();
2631
const newRestrictedDomains = new Map();
27-
2832
let hadWildcard = false;
2933
const newModifiers = [];
3034

@@ -37,7 +41,7 @@ const expandWildcardInNetworkRuleAst = (
3741
const domainList = DomainListParser.parse(modifier.value.value, agtree.PIPE_MODIFIER_SEPARATOR);
3842

3943
for (const domain of domainList.children) {
40-
if (utils.isDomainWithTldWildcard(domain.value)) {
44+
if (utils.isWildcardDomain(domain.value)) {
4145
hadWildcard = true;
4246
const nonWildcardDomains = wildcardDomains[domain.value];
4347
for (const nonWildcardDomain of nonWildcardDomains) {
@@ -100,15 +104,23 @@ const expandWildcardInNetworkRuleAst = (
100104
return newAst;
101105
};
102106

103-
const expandWildcardCosmeticRuleAst = (ast: CosmeticRule, wildcardDomains: WildcardDomainsWithTld): any => {
107+
/**
108+
* Expands wildcards in a cosmetic rule AST.
109+
* @param ast - The cosmetic rule AST to process.
110+
* @param wildcardDomains - A map of wildcard domains to their non-wildcard equivalents.
111+
* @returns The updated cosmetic rule AST with expanded wildcards, or null if no valid domains are left.
112+
*/
113+
const expandCosmeticRulesWildcard = (
114+
ast: CosmeticRule,
115+
wildcardDomains: WildcardDomainsWithTld,
116+
): AnyRule | null => {
104117
const domains = ast.domains.children;
105-
106118
const newPermittedDomains = new Map();
107119
const newRestrictedDomains = new Map();
108-
109120
let hadWildcard = false;
121+
110122
for (const domain of domains) {
111-
if (utils.isDomainWithTldWildcard(domain.value)) {
123+
if (utils.isWildcardDomain(domain.value)) {
112124
hadWildcard = true;
113125
const nonWildcardDomains = wildcardDomains[domain.value];
114126
nonWildcardDomains.forEach((d) => {
@@ -122,18 +134,18 @@ const expandWildcardCosmeticRuleAst = (ast: CosmeticRule, wildcardDomains: Wildc
122134
newPermittedDomains.set(d, newDomain);
123135
}
124136
});
137+
continue;
138+
}
139+
140+
if (domain.exception) {
141+
newRestrictedDomains.set(domain.value, domain);
125142
} else {
126-
// eslint-disable-next-line
127-
if (domain.exception) {
128-
newRestrictedDomains.set(domain.value, domain);
129-
} else {
130-
newPermittedDomains.set(domain.value, domain);
131-
}
143+
newPermittedDomains.set(domain.value, domain);
132144
}
133145
}
134146

135147
if (!hadWildcard) {
136-
return ast;
148+
return ast as AnyRule;
137149
}
138150

139151
const newDomains = [];
@@ -158,22 +170,35 @@ const expandWildcardCosmeticRuleAst = (ast: CosmeticRule, wildcardDomains: Wildc
158170
const newAst = structuredClone(ast);
159171
newAst.domains.children = newDomains;
160172

161-
return newAst;
173+
return newAst as AnyRule;
162174
};
163175

176+
/**
177+
* Expands wildcards in an AST based on its category.
178+
* @param ast - The AST to process.
179+
* @param wildcardDomains - A map of wildcard domains to their non-wildcard equivalents.
180+
* @returns The updated AST with expanded wildcards, or null if no valid domains are left.
181+
* @throws Will throw an error if the AST category is unsupported.
182+
*/
164183
const expandWildcardDomainsInAst = (ast: AnyRule, wildcardDomains: WildcardDomainsWithTld): AnyRule | null => {
165184
switch (ast.category) {
166185
case 'Network':
167-
return expandWildcardInNetworkRuleAst(ast, wildcardDomains);
186+
return expandNetworkRulesWildcard(ast as NetworkRule, wildcardDomains);
168187
case 'Cosmetic':
169-
return expandWildcardCosmeticRuleAst(ast, wildcardDomains);
188+
return expandCosmeticRulesWildcard(ast as CosmeticRule, wildcardDomains);
170189
case 'Comment':
171190
return ast;
172191
default:
173192
throw new Error(`Unsupported rule category: ${ast.category}`);
174193
}
175194
};
176195

196+
/**
197+
* Expands wildcards in a rule string.
198+
* @param rule - The rule string to process.
199+
* @param wildcardDomains - A map of wildcard domains to their non-wildcard equivalents.
200+
* @returns The updated rule string with expanded wildcards, or null if no valid domains are left.
201+
*/
177202
export function expandWildcardsInRule(rule: string, wildcardDomains: WildcardDomainsWithTld): string | null {
178203
const ast = RuleParser.parse(rule);
179204

@@ -189,6 +214,12 @@ export function expandWildcardsInRule(rule: string, wildcardDomains: WildcardDom
189214
return RuleParser.generate(astWithExpandedWildcardDomain);
190215
}
191216

217+
/**
218+
* Patches a filter content by expanding wildcards in all rules.
219+
* @param filterContent - The filter content to patch.
220+
* @param wildcardDomains - A map of wildcard domains to their non-wildcard equivalents.
221+
* @returns The patched filter content with expanded wildcards.
222+
*/
192223
function patchWildcards(filterContent: string, wildcardDomains: WildcardDomainsWithTld): string {
193224
const rules = filterContent.split(/\r?\n/);
194225
const newRules = [];
@@ -203,6 +234,11 @@ function patchWildcards(filterContent: string, wildcardDomains: WildcardDomainsW
203234

204235
const WILDCARD_DOMAINS_FILE = 'wildcard_domains.json';
205236

237+
/**
238+
* Patches platform filter files by expanding wildcards in all rules.
239+
* @param platformsDir - The directory containing the platform filter files.
240+
* @returns A promise that resolves when the patching is complete.
241+
*/
206242
export async function patchPlatforms(platformsDir: string): Promise<void> {
207243
const filters = await findFilterFiles(path.resolve(__dirname, platformsDir), /filters\/\d+(_optimized)?\.txt/);
208244

‎tsconfig.json

+1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
"esModuleInterop": true,
88
"skipLibCheck": true,
99
"forceConsistentCasingInFileNames": true,
10+
"noImplicitAny": true,
1011
"allowJs": true, // Allow JavaScript files
1112
"checkJs": false // Disable type checking for JavaScript files
1213
},

0 commit comments

Comments
 (0)