feat(gui): more ways to filter by name (#683)

* feat(gui): filter name by regex

* feat(gui): filter names exactly by string

* feat(gui): consistent filter operators

* style: apply automatic fixes of linters

* fix(gui): failing tests

Co-authored-by: lars-reimann <[email protected]>

Author: lars-reimann

api-editor/gui/src/common/FilterHelpButton.tsx

@@ -72,12 +72,20 @@ export const FilterHelpButton = function () {
                             </ListItem>
                             <ListItem>
                                 <ChakraText>
-                                    <strong>name:xy</strong>
+                                    <strong>name:[operator][string]</strong>
                                 </ChakraText>
                                 <ChakraText>
-                                    Displays only elements with names that contain the given string xy.
+                                    Displays only elements with matching names (case-sensitive). Replace [operator] with{' '}
+                                    <em>=</em> to display only elements that match the [string] exactly or with{' '}
+                                    <em>~</em> to display only elements that contain the [string] as a substring.
                                 </ChakraText>
                             </ListItem>
+                            <ListItem>
+                                <ChakraText>
+                                    <strong>name:/[regex]/</strong>
+                                </ChakraText>
+                                <ChakraText>Displays only elements with names that match the given [regex].</ChakraText>
+                            </ListItem>
                             <ListItem>
                                 <ChakraText>
                                     <strong>annotation:any</strong>
@@ -104,8 +112,8 @@ export const FilterHelpButton = function () {
                                 </ChakraText>
                                 <ChakraText>
                                     Displays only elements that are used a certain number of times. Replace [operator]
-                                    with one of <em>&lt;, &lt;=, &gt;=, &gt;</em> or omit it to match by equality.
-                                    Replace [expected] with the expected number of usages.
+                                    with one of <em>&lt;, &lt;=, =, &gt;=, &gt;</em>. Replace [expected] with the
+                                    expected number of usages.
                                 </ChakraText>
                             </ListItem>
                             <ListItem>
@@ -114,8 +122,8 @@ export const FilterHelpButton = function () {
                                 </ChakraText>
                                 <ChakraText>
                                     Displays only elements that have a certain usefulness. Replace [operator] with one
-                                    of <em>&lt;, &lt;=, &gt;=, &gt;</em> or omit it to match by equality. Replace
-                                    [expected] with the expected usefulness.
+                                    of <em>&lt;, &lt;=, =, &gt;=, &gt;</em>. Replace [expected] with the expected
+                                    usefulness.
                                 </ChakraText>
                             </ListItem>
                             <ListItem>

api-editor/gui/src/features/packageData/model/filters/AbstractPythonFilter.test.ts

@@ -5,7 +5,7 @@ import { PythonParameter } from '../PythonParameter';
 import { PythonModule } from '../PythonModule';
 import { PythonClass } from '../PythonClass';
 import { PythonFunction } from '../PythonFunction';
-import { NameFilter } from './NameFilter';
+import { NameStringFilter } from './NameStringFilter';
 import { initialAnnotationStore as annotations } from '../../../annotations/annotationSlice';
 import { PythonDeclaration } from '../PythonDeclaration';
 import { UsageCountStore } from '../../../usages/model/UsageCountStore';
@@ -90,7 +90,7 @@ beforeEach(() => {
 
 describe('AbstractPythonFilter::applyToPackage', () => {
     test('keeps modules for which the filter returns true, and their ancestors.', () => {
-        const filter = new NameFilter('test_module_1');
+        const filter = new NameStringFilter('test_module_1', false);
         const filteredPackage = filter.applyToPackage(pythonPackage, annotations, new UsageCountStore());
 
         const modules = filteredPackage.modules;
@@ -104,7 +104,7 @@ describe('AbstractPythonFilter::applyToPackage', () => {
     });
 
     test('keeps classes for which the filter returns true, their ancestors, and their descendants', () => {
-        const filter = new NameFilter('test_class_1');
+        const filter = new NameStringFilter('test_class_1', false);
         const filteredPackage = filter.applyToPackage(pythonPackage, annotations, new UsageCountStore());
 
         const modules = filteredPackage.modules;
@@ -121,7 +121,7 @@ describe('AbstractPythonFilter::applyToPackage', () => {
     });
 
     test('keeps methods for which the filter returns true, their ancestors, and their descendants', () => {
-        const filter = new NameFilter('test_method_1');
+        const filter = new NameStringFilter('test_method_1', false);
         const filteredPackage = filter.applyToPackage(pythonPackage, annotations, new UsageCountStore());
 
         const modules = filteredPackage.modules;
@@ -141,7 +141,7 @@ describe('AbstractPythonFilter::applyToPackage', () => {
     });
 
     test('keeps global functions for which the filter returns true, their ancestors, and their descendants', () => {
-        const filter = new NameFilter('test_global_function_1');
+        const filter = new NameStringFilter('test_global_function_1', false);
         const filteredPackage = filter.applyToPackage(pythonPackage, annotations, new UsageCountStore());
 
         const modules = filteredPackage.modules;
@@ -158,7 +158,7 @@ describe('AbstractPythonFilter::applyToPackage', () => {
     });
 
     test('keeps parameters for which the filter returns true, their ancestors, and their descendants', () => {
-        const filter = new NameFilter('test_parameter_1');
+        const filter = new NameStringFilter('test_parameter_1', false);
         const filteredPackage = filter.applyToPackage(pythonPackage, annotations, new UsageCountStore());
 
         const modules = filteredPackage.modules;

api-editor/gui/src/features/packageData/model/filters/NameFilter.ts renamed to api-editor/gui/src/features/packageData/model/filters/NameRegexFilter.ts

@@ -8,14 +8,18 @@ import { AnnotationStore } from '../../../annotations/annotationSlice';
 import { UsageCountStore } from '../../../usages/model/UsageCountStore';
 
 /**
- * Keeps only declarations that have a given string in their name.
+ * Keeps only declarations that have a name matching the given regex.
  */
-export class NameFilter extends AbstractPythonFilter {
+export class NameRegexFilter extends AbstractPythonFilter {
+    readonly regex: RegExp;
+
     /**
-     * @param substring The string that must be part of the name of the declaration.
+     * @param regex The regex that must match the name of the declaration.
      */
-    constructor(readonly substring: string) {
+    constructor(regex: string) {
         super();
+
+        this.regex = RegExp(regex, 'u');
     }
 
     shouldKeepModule(pythonModule: PythonModule, annotations: AnnotationStore, usages: UsageCountStore): boolean {
@@ -43,6 +47,6 @@ export class NameFilter extends AbstractPythonFilter {
         _annotations: AnnotationStore,
         _usages: UsageCountStore,
     ): boolean {
-        return pythonDeclaration.name.toLowerCase().includes(this.substring.toLowerCase());
+        return this.regex.test(pythonDeclaration.name);
     }
 }

api-editor/gui/src/features/packageData/model/filters/NameStringFilter.ts

@@ -0,0 +1,53 @@
+import { PythonClass } from '../PythonClass';
+import { PythonFunction } from '../PythonFunction';
+import { PythonModule } from '../PythonModule';
+import { PythonParameter } from '../PythonParameter';
+import { AbstractPythonFilter } from './AbstractPythonFilter';
+import { PythonDeclaration } from '../PythonDeclaration';
+import { AnnotationStore } from '../../../annotations/annotationSlice';
+import { UsageCountStore } from '../../../usages/model/UsageCountStore';
+
+/**
+ * Keeps only declarations that have a given string in their name.
+ */
+export class NameStringFilter extends AbstractPythonFilter {
+    /**
+     * @param string The string that must be part of the name of the declaration.
+     * @param matchExactly Whether the name must match the substring exactly.
+     */
+    constructor(readonly string: string, readonly matchExactly: boolean) {
+        super();
+    }
+
+    shouldKeepModule(pythonModule: PythonModule, annotations: AnnotationStore, usages: UsageCountStore): boolean {
+        return this.shouldKeepDeclaration(pythonModule, annotations, usages);
+    }
+
+    shouldKeepClass(pythonClass: PythonClass, annotations: AnnotationStore, usages: UsageCountStore): boolean {
+        return this.shouldKeepDeclaration(pythonClass, annotations, usages);
+    }
+
+    shouldKeepFunction(pythonFunction: PythonFunction, annotations: AnnotationStore, usages: UsageCountStore): boolean {
+        return this.shouldKeepDeclaration(pythonFunction, annotations, usages);
+    }
+
+    shouldKeepParameter(
+        pythonParameter: PythonParameter,
+        annotations: AnnotationStore,
+        usages: UsageCountStore,
+    ): boolean {
+        return this.shouldKeepDeclaration(pythonParameter, annotations, usages);
+    }
+
+    shouldKeepDeclaration(
+        pythonDeclaration: PythonDeclaration,
+        _annotations: AnnotationStore,
+        _usages: UsageCountStore,
+    ): boolean {
+        if (this.matchExactly) {
+            return pythonDeclaration.name === this.string;
+        } else {
+            return pythonDeclaration.name.includes(this.string);
+        }
+    }
+}

api-editor/gui/src/features/packageData/model/filters/filterFactory.test.ts

@@ -2,7 +2,7 @@ import { createFilterFromString, isValidFilterToken } from './filterFactory';
 import { ConjunctiveFilter } from './ConjunctiveFilter';
 import { Visibility, VisibilityFilter } from './VisibilityFilter';
 import { NegatedFilter } from './NegatedFilter';
-import { NameFilter } from './NameFilter';
+import { NameStringFilter } from './NameStringFilter';
 import { UsageFilter } from './UsageFilter';
 import { UsefulnessFilter } from './UsefulnessFilter';
 import { greaterThan } from './comparisons';
@@ -57,13 +57,13 @@ describe('createFilterFromString', () => {
     });
 
     test('handles name filter', () => {
-        const completeFilter = createFilterFromString('name:foo');
+        const completeFilter = createFilterFromString('name:=foo');
         expect(completeFilter).toBeInstanceOf(ConjunctiveFilter);
         expect((completeFilter as ConjunctiveFilter).filters).toHaveLength(1);
 
         const positiveFilter = (completeFilter as ConjunctiveFilter).filters[0];
-        expect(positiveFilter).toBeInstanceOf(NameFilter);
-        expect((positiveFilter as NameFilter).substring).toBe('foo');
+        expect(positiveFilter).toBeInstanceOf(NameStringFilter);
+        expect((positiveFilter as NameStringFilter).string).toBe('foo');
     });
 
     test('handles usages filter', () => {
@@ -93,7 +93,7 @@ describe('isValidFilterToken', () => {
     test.each([
         ['is:public', true],
         ['!is:public', true],
-        ['name:foo', true],
+        ['name:=foo', true],
         ['usages:>2', true],
         ['usefulness:>2', true],
         ['annotation:@calledAfter', true], // https://github.com/lars-reimann/api-editor/issues/669

api-editor/gui/src/features/packageData/model/filters/filterFactory.ts

@@ -1,5 +1,5 @@
 import { ConjunctiveFilter } from './ConjunctiveFilter';
-import { NameFilter } from './NameFilter';
+import { NameStringFilter } from './NameStringFilter';
 import { AbstractPythonFilter } from './AbstractPythonFilter';
 import { DeclarationType, DeclarationTypeFilter } from './DeclarationTypeFilter';
 import { Visibility, VisibilityFilter } from './VisibilityFilter';
@@ -12,6 +12,7 @@ import { equals, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual } fr
 import { ParameterAssignmentFilter } from './ParameterAssignmentFilter';
 import { PythonParameterAssignment } from '../PythonParameter';
 import { RequiredOrOptional, RequiredOrOptionalFilter } from './RequiredOrOptionalFilter';
+import { NameRegexFilter } from './NameRegexFilter';
 
 /**
  * Creates a filter from the given string. This method handles conjunctions, negations, and non-negated tokens.
@@ -124,13 +125,19 @@ const parsePositiveToken = function (token: string): Optional<AbstractPythonFilt
     }
 
     // Name
-    const nameMatch = /^name:(?<name>\w+)$/u.exec(token);
-    if (nameMatch) {
-        return new NameFilter(nameMatch?.groups?.name as string);
+    const nameStringMatch = /^name:(?<comparison>[=~])(?<name>\w+)$/u.exec(token);
+    if (nameStringMatch) {
+        const comparisonOperator = nameStringMatch?.groups?.comparison as string;
+        return new NameStringFilter(nameStringMatch?.groups?.name as string, comparisonOperator === '=');
+    }
+
+    const nameRegexMatch = /^name:\/(?<regex>.*)\/$/u.exec(token);
+    if (nameRegexMatch) {
+        return new NameRegexFilter(nameRegexMatch?.groups?.regex as string);
     }
 
     // Usages
-    const usageMatch = /^usages(?<comparison>:(<|<=|>=|>)?)(?<expected>\d+)$/u.exec(token);
+    const usageMatch = /^usages:(?<comparison>(<|<=|=|>=|>)?)(?<expected>\d+)$/u.exec(token);
     if (usageMatch) {
         const comparisonOperator = usageMatch?.groups?.comparison as string;
         const comparison = comparisonFunction(comparisonOperator);
@@ -144,7 +151,7 @@ const parsePositiveToken = function (token: string): Optional<AbstractPythonFilt
     }
 
     // Usefulness
-    const usefulnessMatch = /^usefulness(?<comparison>:(<|<=|>=|>)?)(?<expected>\d+)$/u.exec(token);
+    const usefulnessMatch = /^usefulness:(?<comparison>(<|<=|=|>=|>)?)(?<expected>\d+)$/u.exec(token);
     if (usefulnessMatch) {
         const comparisonOperator = usefulnessMatch?.groups?.comparison as string;
         const comparison = comparisonFunction(comparisonOperator);
@@ -160,15 +167,15 @@ const parsePositiveToken = function (token: string): Optional<AbstractPythonFilt
 
 const comparisonFunction = function (comparisonOperator: string): ((a: number, b: number) => boolean) | null {
     switch (comparisonOperator) {
-        case ':<':
+        case '<':
             return lessThan;
-        case ':<=':
+        case '<=':
             return lessThanOrEqual;
-        case ':':
+        case '=':
             return equals;
-        case ':>=':
+        case '>=':
             return greaterThanOrEqual;
-        case ':>':
+        case '>':
             return greaterThan;
         default:
             return null;