refactor: update code structure, main class, and add new tests

misc/swift-file-samples/Enzo.swift

@@ -0,0 +1,133 @@
+/*
+"DecorativeView.swift" file from the iOS SwiftUI Accessibility Techniques
+project from CVS Health, modified to be used in the tests.
+*/
+
+/*
+   Copyright 2023 CVS Health and/or one of its affiliates
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+ */
+
+import SwiftUI
+
+struct DecorativeView: View {
+
+    private var darkGreen = Color(red: 0 / 255, green: 102 / 255, blue: 0 / 255)
+    private var darkRed = Color(red: 220 / 255, green: 20 / 255, blue: 60 / 255)
+    @Environment(\.colorScheme) var colorScheme
+
+    var body: some View {
+        ScrollView {
+            VStack {
+                Text("Decorative images are used purely for decoration and convey no meaning to sighted users. Decorative images must be hidden from VoiceOver users. Use `Image(decorative:)` or `.accessibilityHidden(true)` to hide decorative images from VoiceOver.")
+                    .padding(.bottom)
+                Text("Good Examples")
+                    .font(.subheadline)
+                    .fontWeight(.bold)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .accessibilityAddTraits(.isHeader)
+                    .foregroundColor(colorScheme == .dark ? Color(.systemGreen) : darkGreen)
+                Divider()
+                    .frame(height: 2.0, alignment:.leading)
+                    .background(colorScheme == .dark ? Color(.systemGreen) : darkGreen)
+                    .padding(.bottom)
+                Text("Good Example `Image(decorative:)`")
+                    .font(.subheadline)
+                    .fontWeight(.bold)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .accessibilityAddTraits(.isHeader)
+                Image(decorative: "newspaper")
+                    .resizable()
+                    .aspectRatio(contentMode: .fit)
+                    .frame(width: 100, height: 100)
+                    .accessibilityIdentifier("goodImage")
+                Text("Discover new offers every week and earn extra savings.")
+                Link(destination: URL(string: "https://www.example.com/weeklyad")!) {
+                    Text("Shop weekly ad")
+                        .underline()
+                        .padding(.bottom, 10)
+                }
+                DisclosureGroup("Details") {
+                    Text("The good decorative image example uses `Image(decorative: \"newspaper\")` which prevents VoiceOver from focusing on the image.")
+                }.padding(.bottom).accessibilityHint("Good Example Image(decorative:)")
+                Text("Good Example `.accessibilityHidden(true)`")
+                    .font(.subheadline)
+                    .fontWeight(.bold)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .accessibilityAddTraits(.isHeader)
+                Image(systemName: "globe")
+                    .imageScale(.large)
+                    .foregroundColor(.accentColor)
+                    .accessibilityHidden(true)
+                    .accessibilityIdentifier("goodIcon")
+                Text("Hello, world!")
+                DisclosureGroup("Details") {
+                    Text("The good decorative icon image example uses `.accessibilityHidden(true)` which prevents VoiceOver from focusing on the icon.")
+                }.padding(.bottom).accessibilityHint("Good Example `.accessibilityHidden(true)`")
+                Text("Bad Examples")
+                    .font(.subheadline)
+                    .fontWeight(.bold)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .accessibilityAddTraits(.isHeader)
+                    .foregroundColor(colorScheme == .dark ? Color(.systemRed) : darkRed)
+                Divider()
+                    .frame(height: 2.0, alignment:.leading)
+                    .background(colorScheme == .dark ? Color(.systemRed) : darkRed)
+                    .padding(.bottom)
+                Text("Bad Example Missing `Image(decorative:)`")
+                    .font(.subheadline)
+                    .fontWeight(.bold)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .accessibilityAddTraits(.isHeader)
+                Image("newspaper")
+                    .resizable()
+                    .aspectRatio(contentMode: .fit)
+                    .frame(width: 100, height: 100)
+                    .accessibilityIdentifier("badImage")
+                Text("Discover new offers every week and earn extra savings.")
+                Link(destination: URL(string: "https://www.example.com/weeklyad")!) {
+                    Text("Shop weekly ad")
+                        .underline()
+                        .padding(.bottom, 10)
+                }
+                DisclosureGroup("Details") {
+                    Text("The bad decorative image example does not use the `decorative:` parameter which allows VoiceOver to focus on the image and read \"newspaper\" as its accessibility label.")
+                }.padding(.bottom).accessibilityHint("Bad Example Missing `Image(decorative:)`")
+                Text("Bad Example Missing `.accessibilityHidden(true)`")
+                    .font(.subheadline)
+                    .fontWeight(.bold)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .accessibilityAddTraits(.isHeader)
+                Image(systemName: "globe")
+                    .imageScale(.large)
+                    .foregroundColor(.accentColor)
+                    .accessibilityIdentifier("badIcon")
+                Text("Hello, world!")
+                DisclosureGroup("Details") {
+                    Text("The bad decorative icon image example does not use `.accessibilityHidden(true)` which allows VoiceOver to focus on the image and read \"globe\" as its accessibility label.")
+                }.padding(.bottom).accessibilityHint("Bad Example Missing `.accessibilityHidden(true)`")
+            }
+            .navigationTitle("Decorative Images")
+            .padding()
+        }
+    }
+}
+
+struct DecorativeView_Previews: PreviewProvider {
+    static var previews: some View {
+        NavigationStack {
+            DecorativeView()
+        }
+    }
+}

misc/swift-file-samples/Enzo_noImageDecorativeLabel.swift

@@ -0,0 +1,133 @@
+/*
+"DecorativeView.swift" file from the iOS SwiftUI Accessibility Techniques
+project from CVS Health, modified to be used in the tests.
+*/
+
+/*
+   Copyright 2023 CVS Health and/or one of its affiliates
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+ */
+
+import SwiftUI
+
+struct DecorativeView: View {
+
+    private var darkGreen = Color(red: 0 / 255, green: 102 / 255, blue: 0 / 255)
+    private var darkRed = Color(red: 220 / 255, green: 20 / 255, blue: 60 / 255)
+    @Environment(\.colorScheme) var colorScheme
+
+    var body: some View {
+        ScrollView {
+            VStack {
+                Text("Decorative images are used purely for decoration and convey no meaning to sighted users. Decorative images must be hidden from VoiceOver users. Use `Image(decorative:)` or `.accessibilityHidden(true)` to hide decorative images from VoiceOver.")
+                    .padding(.bottom)
+                Text("Good Examples")
+                    .font(.subheadline)
+                    .fontWeight(.bold)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .accessibilityAddTraits(.isHeader)
+                    .foregroundColor(colorScheme == .dark ? Color(.systemGreen) : darkGreen)
+                Divider()
+                    .frame(height: 2.0, alignment:.leading)
+                    .background(colorScheme == .dark ? Color(.systemGreen) : darkGreen)
+                    .padding(.bottom)
+                Text("Good Example `Image(decorative:)`")
+                    .font(.subheadline)
+                    .fontWeight(.bold)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .accessibilityAddTraits(.isHeader)
+                Image("newspaper")
+                    .resizable()
+                    .aspectRatio(contentMode: .fit)
+                    .frame(width: 100, height: 100)
+                    .accessibilityIdentifier("goodImage")
+                Text("Discover new offers every week and earn extra savings.")
+                Link(destination: URL(string: "https://www.example.com/weeklyad")!) {
+                    Text("Shop weekly ad")
+                        .underline()
+                        .padding(.bottom, 10)
+                }
+                DisclosureGroup("Details") {
+                    Text("The good decorative image example uses `Image(decorative: \"newspaper\")` which prevents VoiceOver from focusing on the image.")
+                }.padding(.bottom).accessibilityHint("Good Example Image(decorative:)")
+                Text("Good Example `.accessibilityHidden(true)`")
+                    .font(.subheadline)
+                    .fontWeight(.bold)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .accessibilityAddTraits(.isHeader)
+                Image(systemName: "globe")
+                    .imageScale(.large)
+                    .foregroundColor(.accentColor)
+                    .accessibilityHidden(true)
+                    .accessibilityIdentifier("goodIcon")
+                Text("Hello, world!")
+                DisclosureGroup("Details") {
+                    Text("The good decorative icon image example uses `.accessibilityHidden(true)` which prevents VoiceOver from focusing on the icon.")
+                }.padding(.bottom).accessibilityHint("Good Example `.accessibilityHidden(true)`")
+                Text("Bad Examples")
+                    .font(.subheadline)
+                    .fontWeight(.bold)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .accessibilityAddTraits(.isHeader)
+                    .foregroundColor(colorScheme == .dark ? Color(.systemRed) : darkRed)
+                Divider()
+                    .frame(height: 2.0, alignment:.leading)
+                    .background(colorScheme == .dark ? Color(.systemRed) : darkRed)
+                    .padding(.bottom)
+                Text("Bad Example Missing `Image(decorative:)`")
+                    .font(.subheadline)
+                    .fontWeight(.bold)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .accessibilityAddTraits(.isHeader)
+                Image("newspaper")
+                    .resizable()
+                    .aspectRatio(contentMode: .fit)
+                    .frame(width: 100, height: 100)
+                    .accessibilityIdentifier("badImage")
+                Text("Discover new offers every week and earn extra savings.")
+                Link(destination: URL(string: "https://www.example.com/weeklyad")!) {
+                    Text("Shop weekly ad")
+                        .underline()
+                        .padding(.bottom, 10)
+                }
+                DisclosureGroup("Details") {
+                    Text("The bad decorative image example does not use the `decorative:` parameter which allows VoiceOver to focus on the image and read \"newspaper\" as its accessibility label.")
+                }.padding(.bottom).accessibilityHint("Bad Example Missing `Image(decorative:)`")
+                Text("Bad Example Missing `.accessibilityHidden(true)`")
+                    .font(.subheadline)
+                    .fontWeight(.bold)
+                    .frame(maxWidth: .infinity, alignment: .leading)
+                    .accessibilityAddTraits(.isHeader)
+                Image(systemName: "globe")
+                    .imageScale(.large)
+                    .foregroundColor(.accentColor)
+                    .accessibilityIdentifier("badIcon")
+                Text("Hello, world!")
+                DisclosureGroup("Details") {
+                    Text("The bad decorative icon image example does not use `.accessibilityHidden(true)` which allows VoiceOver to focus on the image and read \"globe\" as its accessibility label.")
+                }.padding(.bottom).accessibilityHint("Bad Example Missing `.accessibilityHidden(true)`")
+            }
+            .navigationTitle("Decorative Images")
+            .padding()
+        }
+    }
+}
+
+struct DecorativeView_Previews: PreviewProvider {
+    static var previews: some View {
+        NavigationStack {
+            DecorativeView()
+        }
+    }
+}

src/deaccessibilizer.ts

@@ -1,32 +1,123 @@
 import Parser, { QueryMatch } from 'web-tree-sitter';
 import { SwiftFileTree } from './parsing/swift-file-tree.js';
 import { getParser } from './configuring/get-parser.js';
-import { FaultTransformationRule } from './transforming/fault-transformation-rule.js';
+import {
+  FaultTransformationOptions,
+  FaultTransformationRule,
+} from './transforming/fault-transformation-rule.js';
+import { RulesDictionary } from './transforming/rules-dictionary.js';
+import { CodeTransformation } from './transforming/code-transformation.js';
+import { byNodePosition } from './utils.js';
+
+const allRules = Object.values(RulesDictionary);
 
 /**
- * The main class of the library, responsible for handling Swift files, creating syntax trees, performing queries, and transforming code.
+ * The main class of the library, responsible for handling Swift files, creating syntax trees,
+ * performing queries, and transforming code.
  *
  * @category Main
  */
 export class Deaccessibilizer {
   private parser: Promise<Parser>;
 
+  /**
+   * Create a new instance of the Deaccessibilizer. Gets the tree-sitter parser for Swift,
+   * considering whether it is running in Node.js or WebAssembly.
+   */
   constructor() {
     this.parser = getParser() as unknown as Promise<Parser>;
   }
 
+  /**
+   * Create a Swift file tree from the given file text.
+   */
   async createSwiftFileTree(fileText: string): Promise<SwiftFileTree> {
     const parser = await this.parser;
     return new SwiftFileTree(fileText, parser);
   }
 
-  async queryFromRule(tree: SwiftFileTree, rule: FaultTransformationRule) {
-    const matches: QueryMatch[] = [];
+  /**
+   * Query a Swift file tree with a [query in tree-sitter syntax](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries).
+   */
+  queryEntireTree(tree: SwiftFileTree, query: string): QueryMatch[] {
+    return tree.queryNode(tree.tree.rootNode, query);
+  }
 
-    for (const view of tree.swiftUIViews) {
-      matches.push(...tree.queryNode(view, rule.queryText));
+  /**
+   * Query the SwiftUI views in the file tree with a [query in tree-sitter syntax](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries).
+   */
+  querySwiftUIViews(tree: SwiftFileTree, query: string): QueryMatch[] {
+    return tree.swiftUIViews.flatMap((view) => tree.queryNode(view, query));
+  }
+
+  /**
+   * Get the code transformations introducing a fault that can be applied to the given tree,
+   * based on the given rules. If no rules are provided, all rules are considered.
+   */
+  getFaultTransformations(
+    tree: SwiftFileTree,
+    rules: FaultTransformationRule[] = allRules,
+    options: FaultTransformationOptions = {
+      substituteWithComment: false,
+    },
+  ): CodeTransformation[] {
+    return rules.flatMap((rule) =>
+      this.querySwiftUIViews(tree, rule.queryText).map((match) =>
+        rule.getFaultTransformation(match, options),
+      ),
+    );
+  }
+
+  /**
+   * Apply the given code transformations to the tree.
+   *
+   * This method is faster than {@link applyFaultTransformationsToTreeWithRebuild},
+   * but it is less safe, since it sorts and applies all transformations at once.
+   *
+   * This is reccomended for small batches of code transformations.
+   */
+  applyCodeTransformationsToTree(
+    tree: SwiftFileTree,
+    codeTransformations: CodeTransformation[],
+  ) {
+    const nodeChanges = codeTransformations
+      .flatMap((transformation) => transformation.nodeChanges)
+      .sort(byNodePosition)
+      .reverse();
+
+    for (const nodeChange of nodeChanges) {
+      tree.replaceNode(
+        nodeChange.node,
+        nodeChange.replaceWith,
+        nodeChange.replaceOptions,
+      );
     }
+  }
 
-    return matches;
+  /**
+   * Get the fault transformations from the given rules and apply them directly to the tree.
+   * If no rules are provided, all rules are considered.
+   *
+   * This method is safer than {@link applyCodeTransformationsToTree}, since it applies
+   * one rule at a time and rebuilds the tree after each transformation.
+   *
+   * This is reccomended for large batches of code transformations.
+   */
+  applyFaultTransformationsToTreeWithRebuild(
+    tree: SwiftFileTree,
+    rules: FaultTransformationRule[] = allRules,
+    options: FaultTransformationOptions = {
+      substituteWithComment: false,
+    },
+  ) {
+    for (const rule of rules) {
+      const transformation = this.getFaultTransformations(
+        tree,
+        [rule],
+        options,
+      );
+      this.applyCodeTransformationsToTree(tree, transformation);
+      tree.remountTree();
+    }
   }
 }