refscan 0.2.4__tar.gz → 0.3.0__tar.gz

{refscan-0.2.4 → refscan-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: refscan
-Version: 0.2.4
+Version: 0.3.0
 Summary: Command-line program that scans the NMDC MongoDB database for referential integrity violations
 Keywords: mongodb,mongo,relationships,reference,database,data,referential integrity,scan
 Requires-Python: >=3.9,<4.0
@@ -313,6 +313,16 @@ While editing the tool's source code, you can run the tool as you normally would
 poetry run refscan --help
 ```
 
+### Check types
+
+We use [mypy](https://mypy.readthedocs.io/en/stable/) as the static type checker for `refscan`.
+
+You can perform static type checking by running the following command from the root directory of the repository:
+
+```shell
+poetry run mypy
+```
+
 ### Run tests
 
 We use [pytest](https://docs.pytest.org/en/8.2.x/) as the testing framework for `refscan`.

{refscan-0.2.4 → refscan-0.3.0}/README.md

@@ -292,6 +292,16 @@ While editing the tool's source code, you can run the tool as you normally would
 poetry run refscan --help
 ```
 
+### Check types
+
+We use [mypy](https://mypy.readthedocs.io/en/stable/) as the static type checker for `refscan`.
+
+You can perform static type checking by running the following command from the root directory of the repository:
+
+```shell
+poetry run mypy
+```
+
 ### Run tests
 
 We use [pytest](https://docs.pytest.org/en/8.2.x/) as the testing framework for `refscan`.

{refscan-0.2.4 → refscan-0.3.0}/pyproject.toml

@@ -2,7 +2,7 @@
 
 [tool.poetry]
 name = "refscan"
-version = "v0.2.4"
+version = "v0.3.0"
 description = "Command-line program that scans the NMDC MongoDB database for referential integrity violations"
 authors = []
 readme = "README.md"
@@ -43,6 +43,10 @@ pytest-cov = "^5.0.0"
 # We use `mongomock` to test MongoDB interaction without involving a real MongoDB instance.
 # Docs: https://github.com/mongomock/mongomock
 mongomock = "^4.3.0"
+# We use `mypy` to perform static type checking.
+# Usage: $ poetry run mypy
+# Docs: https://mypy.readthedocs.io/en/stable/
+mypy = "^1.16.0"
 
 [tool.poetry.scripts]
 # Reference: https://python-poetry.org/docs/pyproject#scripts
@@ -61,6 +65,25 @@ addopts = "--doctest-modules --cov=refscan"
 # Reference: https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-format
 line-length = 120
 
+[tool.mypy]
+# Make it so, when someone runs `$ poetry run mypy`, these default CLI options are used.
+# Reference: https://mypy.readthedocs.io/en/stable/config_file.html
+files = "."
+
+[[tool.mypy.overrides]]
+# Silence the following error:
+# > Skipping analyzing "linkml_runtime": module is installed, but missing library stubs or py.typed marker  [import-untyped] 
+#
+# Note: We first tried using the following, but it seemed to have no effect on the behavior of mypy when run via `$ poetry run mypy`.
+#       ```
+#       [mypy-linkml_runtime]
+#       ignore_missing_imports = true
+#       ```
+#       So, we—instead—used the syntax shown on: https://stackoverflow.com/a/74198016
+#
+module = "linkml_runtime"
+ignore_missing_imports = true
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"

{refscan-0.2.4 → refscan-0.3.0}/refscan/__init__.py

@@ -12,7 +12,7 @@ def get_package_metadata(key: str) -> str:
     metadata_value = ""
     try:
         package_metadata = metadata("refscan")
-        metadata_value = package_metadata.get(key)
+        metadata_value = package_metadata.get(key, "")
     except PackageNotFoundError:
         pass
     return metadata_value

{refscan-0.2.4 → refscan-0.3.0}/refscan/cli/scan.py

@@ -8,10 +8,10 @@ import linkml_runtime
 from refscan.lib.constants import console
 from refscan.lib.helpers import (
     connect_to_database,
+    get_collection_name_to_class_names_map,
     get_collection_names_from_schema,
     get_lowercase_key,
     print_section_header,
-    get_names_of_classes_eligible_for_collection,
     identify_references,
 )
 from refscan.lib.ViolationList import ViolationList
@@ -134,12 +134,7 @@ def scan(
     console.print(f"Collections described by schema: {len(collection_names)}")
 
     # For each collection, determine the names of the classes whose instances can be stored in that collection.
-    collection_name_to_class_names = {}  # example: { "study_set": ["Study"] }
-    for collection_name in sorted(collection_names):
-        collection_name_to_class_names[collection_name] = get_names_of_classes_eligible_for_collection(
-            schema_view=schema_view,
-            collection_name=collection_name,
-        )
+    collection_name_to_class_names = get_collection_name_to_class_names_map(schema_view=schema_view)
 
     # Identify the inter-document references that the schema allows to exist.
     references = identify_references(
@@ -177,7 +172,6 @@ def scan(
         db=db,
         schema_view=schema_view,
         references=references,
-        collection_names=collection_names,
         names_of_source_collections_to_skip=names_of_source_collections_to_skip,
         user_wants_to_locate_misplaced_documents=user_wants_to_locate_misplaced_documents,
         verbose=verbose,

{refscan-0.2.4 → refscan-0.3.0}/refscan/grapher.py

@@ -1,6 +1,5 @@
 from enum import Enum
-from pathlib import Path
-from typing import Union
+from typing import Union, List, Dict, Any
 import json
 import base64
 from importlib import resources
@@ -10,12 +9,17 @@ import linkml_runtime
 from refscan import get_package_metadata
 from refscan.lib.constants import console
 from refscan.lib.helpers import (
+    get_collection_name_to_class_names_map,
     print_section_header,
     get_collection_names_from_schema,
-    get_names_of_classes_eligible_for_collection,
     identify_references,
 )
 
+# Define some type aliases that we can reference later, to simplify the latter type hints.
+# TODO: Update these type hints to not use `Any`.
+NodeType = Dict[str, Dict[str, Any]]
+EdgeType = Dict[str, Dict[str, Any]]
+
 
 class Subject(str, Enum):
     r"""The subject (i.e. focal point) of the graph."""
@@ -78,12 +82,7 @@ def graph(
     console.print(f"Collections described by schema: {len(collection_names)}")
 
     # For each collection, determine the names of the classes whose instances can be stored in that collection.
-    collection_name_to_class_names = {}  # example: { "study_set": ["Study"] }
-    for collection_name in sorted(collection_names):
-        collection_name_to_class_names[collection_name] = get_names_of_classes_eligible_for_collection(
-            schema_view=schema_view,
-            collection_name=collection_name,
-        )
+    collection_name_to_class_names = get_collection_name_to_class_names_map(schema_view=schema_view)
 
     # Identify the inter-document references that the schema allows to exist.
     references = identify_references(
@@ -111,8 +110,8 @@ def graph(
     #
     # Reference: https://js.cytoscape.org/#notation/elements-json
     #
-    nodes = []
-    edges = []
+    nodes: List[NodeType] = []
+    edges: List[EdgeType] = []
     for r in references:
         # Get the source and target names depending upon the subject of the graph.
         source_name = r.source_collection_name if subject == Subject.collection else r.source_class_name

{refscan-0.2.4 → refscan-0.3.0}/refscan/lib/Finder.py

@@ -1,4 +1,4 @@
-from typing import List, Optional, Dict
+from typing import List, Optional, Dict, Tuple
 
 from pymongo.database import Database
 from pymongo.client_session import ClientSession
@@ -24,8 +24,8 @@ class Finder:
         #       from source documents that we process _temporally close_ to one another, likely point to target
         #       documents residing _in the same collections_ as one another.
         #
-        self.cached_collection_names_where_recently_found = []
-        self.cache_size = 2  # we'll cache up to 2 collection names
+        self.cached_collection_names_where_recently_found: List[str] = []
+        self.cache_size: int = 2  # we'll cache up to 2 collection names
 
         # Initialize our cache of document `id` presences/absences by collection.
         #
@@ -118,7 +118,7 @@ class Finder:
             return self.cached_id_presence_by_collection[collection_name][document_id]
 
     def check_whether_document_having_id_exists_among_collections(
-        self, document_id: str, collection_names: List[str], client_session: ClientSession = None
+        self, document_id: str, collection_names: List[str], client_session: Optional[ClientSession] = None
     ) -> Optional[str]:
         r"""
         Checks whether any document in any of the specified collections has the specified value in its `id` field.
@@ -182,3 +182,48 @@ class Finder:
             )
 
         return name_of_collection_containing_target_document
+
+    def find_documents_having_type_and_value_in_field(
+        self,
+        collection_name: str,
+        type_and_field_name_tuples: List[Tuple[str, str]],
+        value: str,
+        client_session: Optional[ClientSession] = None,
+    ) -> List[dict]:
+        r"""
+        Finds all documents residing in the specified collection that—for any of the specified
+        `type`-and-`field_name` combinations—have both (a) that `type` value and (b) the specified
+        `value` value in their `field_name` field. Returns a list of descriptors of those
+        documents (each descriptor consists of the document's `_id`, `id`, and `type`).
+
+        For example, if the `type_and_field_name_tuples` parameter contains the tuple
+        `("nmdc:Study", "part_of")`, and the `value` parameter is `"nmdc:sty-00-000001"`,
+        then this function will return all documents in the specified collection where both
+        (a) the document's `type` field contains the value `"nmdc:Study"` and
+        (b) the document's `part_of` field contains the value `"nmdc:sty-00-000001"`.
+
+        Note: `type_and_field_name_tuples` is a list of tuples, where the first item in each tuple is a
+              `type` value (e.g. "nmdc:Study") and the second item is a field name (e.g. "part_of").
+
+        If a `pymongo.client_session.ClientSession` is specified, this function will access the database within
+        the context of that session.
+        """
+
+        # Build the query filter terms based on the `type`-and-`field_name` tuples.
+        query_filter_terms = []
+        for type_and_field_name_tuple in type_and_field_name_tuples:
+            type_value, field_name = type_and_field_name_tuple
+            query_filter_term = {"type": type_value, field_name: value}
+            query_filter_terms.append(query_filter_term)
+
+        # Define the overall query filter as a logical "OR" of the individual terms.
+        query_filter = {"$or": query_filter_terms}
+
+        # Only request essential data from the database (as a performance optimization).
+        projection = ["_id", "id", "type"]
+
+        documents = []
+        collection = self.db.get_collection(collection_name)
+        for document in collection.find(query_filter, projection=projection, session=client_session):
+            documents.append(document)
+        return documents

{refscan-0.2.4 → refscan-0.3.0}/refscan/lib/ReferenceList.py

@@ -1,4 +1,4 @@
-from typing import List, Dict, Union
+from typing import List, Dict, Union, Optional
 from pathlib import Path
 from dataclasses import fields, astuple
 from collections import UserList
@@ -18,6 +18,17 @@ class ReferenceList(UserList):
           One thing it does is enable sorting via `sorted(the_list)`.
     """
 
+    # A cached dictionary that maps source class names to a list of the names of
+    # the fields of that class that contain references. Initialized to `None` to
+    # indicate that it hasn't been computed/cached yet.
+    #
+    # Example: {"Study": ["part_of"]}
+    #
+    # TODO: Consider implementing caching via functools's `@cached_property` decorator instead.
+    #       Reference: https://docs.python.org/3/library/functools.html#functools.cached_property
+    #
+    _reference_field_names_by_source_class_name: Optional[Dict[str, List[str]]] = None
+
     def get_source_collection_names(self) -> list[str]:
         """
         Returns the distinct `source_collection_names` values among all references in the list.
@@ -101,11 +112,16 @@ class ReferenceList(UserList):
 
     def get_reference_field_names_by_source_class_name(self) -> Dict[str, List[str]]:
         r"""
-        Returns a dictionary that maps source class names to a list of the
-        names of the fields of that class that contain references.
+        Returns a dictionary that maps source class names to a list of the names of
+        the fields of that class that contain references.
 
         Example: {"Study": ["part_of"]}
         """
+
+        # If this dictionary has already been computed by this class, return that cached dictionary.
+        if isinstance(self._reference_field_names_by_source_class_name, dict):
+            return self._reference_field_names_by_source_class_name
+
         reference_field_names_by_source_class_name: Dict[str, List[str]] = {}
         for reference in self.data:
             source_class_name = reference.source_class_name
@@ -119,8 +135,40 @@ class ReferenceList(UserList):
             if source_field_name not in reference_field_names_by_source_class_name[source_class_name]:
                 reference_field_names_by_source_class_name[source_class_name].append(source_field_name)
 
+        # Cache the dictionary for subsequent invocations of this method.
+        self._reference_field_names_by_source_class_name = reference_field_names_by_source_class_name
+
         return reference_field_names_by_source_class_name
 
+    def get_by_target_class_name(self, target_class_name: str) -> "ReferenceList":
+        r"""
+        Returns a new `ReferenceList` that contains only the references whose target class
+        has the specified name.
+
+        Maintainer note: The return type is written as a string to avoid the error:
+                         > NameError: name 'ReferenceList' is not defined
+        """
+
+        filtered_references = ReferenceList()
+        for reference in self.data:
+            if reference.target_class_name == target_class_name:
+                filtered_references.append(reference)
+        return filtered_references
+
+    def group_by_source_collection_name(self) -> Dict[str, "ReferenceList"]:
+        r"""
+        Returns a dictionary that maps source collection names to `ReferenceList` instances
+        containing the references that have that source collection name.
+        """
+
+        grouped_references: Dict[str, ReferenceList] = {}
+        for reference in self.data:
+            if reference.source_collection_name not in grouped_references:
+                grouped_references[reference.source_collection_name] = ReferenceList()
+            grouped_references[reference.source_collection_name].append(reference)
+
+        return grouped_references
+
     def as_table(self) -> Table:
         r"""
         Returns the references as a `rich.Table` instance.

{refscan-0.2.4 → refscan-0.3.0}/refscan/lib/helpers.py

@@ -1,4 +1,4 @@
-from typing import Optional, List
+from typing import Optional, List, Dict
 from functools import cache
 
 from pymongo import MongoClient, timeout
@@ -18,6 +18,8 @@ def connect_to_database(mongo_uri: str, database_name: str, verbose: bool = True
     mongo_client: MongoClient = MongoClient(host=mongo_uri, directConnection=True)
 
     with timeout(5):  # if any message exchange takes > 5 seconds, this will raise an exception
+        if mongo_client.address is None:
+            raise ValueError("Failed to determine MongoDB server hostname or port number.")
         (host, port_number) = mongo_client.address
 
         if verbose:
@@ -30,6 +32,7 @@ def connect_to_database(mongo_uri: str, database_name: str, verbose: bool = True
     return mongo_client
 
 
+@cache  # memoizes the decorated function
 def get_collection_names_from_schema(schema_view: SchemaView) -> list[str]:
     """
     Returns the names of the slots of the `Database` class that describe database collections.
@@ -53,6 +56,7 @@ def get_collection_names_from_schema(schema_view: SchemaView) -> list[str]:
     return collection_names
 
 
+@cache  # memoizes the decorated function
 def get_names_of_classes_eligible_for_collection(schema_view: SchemaView, collection_name: str) -> list[str]:
     r"""
     Returns a list of the names of the classes whose instances can be stored in the specified collection,
@@ -65,6 +69,30 @@ def get_names_of_classes_eligible_for_collection(schema_view: SchemaView, collec
     return names_of_eligible_classes
 
 
+@cache  # memoizes the decorated function
+def get_collection_name_to_class_names_map(
+    schema_view: SchemaView,
+) -> Dict[str, List[str]]:
+    r"""
+    Returns a mapping of collection names to the names of the classes whose instances can be stored
+    in those collections, according to the specified `SchemaView`.
+
+    Example output:
+    ```
+    {
+        "study_set": ["Study"],
+        "biosample_set": ["Biosample"],
+        ...
+    }
+    ```
+    """
+    collection_name_to_class_names = {}
+    for collection_name in get_collection_names_from_schema(schema_view):
+        class_names = get_names_of_classes_eligible_for_collection(schema_view, collection_name)
+        collection_name_to_class_names[collection_name] = class_names
+    return collection_name_to_class_names
+
+
 @cache  # memoizes the decorated function
 def translate_class_uri_into_schema_class_name(schema_view: SchemaView, class_uri: str) -> Optional[str]:
     r"""
@@ -85,6 +113,22 @@ def translate_class_uri_into_schema_class_name(schema_view: SchemaView, class_ur
     return schema_class_name
 
 
+@cache  # memoizes the decorated function
+def translate_schema_class_name_into_class_uri(schema_view: SchemaView, schema_class_name: str) -> Optional[str]:
+    r"""
+    Returns the `class_uri` of the schema class having the specified name.
+
+    Example: "Biosample" (a schema class name) -> "nmdc:Biosample" (a `class_uri` value)
+    """
+    class_uri = None
+    all_class_definitions_in_schema = schema_view.all_classes()
+    for class_name, class_definition in all_class_definitions_in_schema.items():
+        if class_name == schema_class_name:
+            class_uri = class_definition.class_uri
+            break
+    return class_uri
+
+
 def derive_schema_class_name_from_document(schema_view: SchemaView, document: dict) -> Optional[str]:
     r"""
     Returns the name of the schema class, if any, of which the specified document claims to represent an instance.

{refscan-0.2.4 → refscan-0.3.0}/refscan/scanner.py

@@ -1,4 +1,4 @@
-from typing import List, Optional, Dict
+from typing import List, Optional, Dict, Set, Tuple
 
 from pymongo.database import Database
 from pymongo.client_session import ClientSession
@@ -8,6 +8,9 @@ from linkml_runtime import SchemaView
 from refscan.lib.Finder import Finder
 from refscan.lib.helpers import (
     derive_schema_class_name_from_document,
+    get_collection_names_from_schema,
+    translate_class_uri_into_schema_class_name,
+    translate_schema_class_name_into_class_uri,
     init_progress_bar,
 )
 from refscan.lib.ReferenceList import ReferenceList
@@ -16,16 +19,102 @@ from refscan.lib.ViolationList import ViolationList
 from refscan.lib.constants import console as default_console
 
 
+def identify_referring_documents(
+    document: dict,
+    schema_view: SchemaView,
+    references: ReferenceList,
+    finder: Finder,
+    client_session: Optional[ClientSession] = None,
+) -> List[dict]:
+    r"""
+    Identifies documents that reference the specified one.
+
+    Note: This function only searches collections and fields that the _schema_ says
+          can reference the specified document. If an arbitrary collection contains
+          a document that has a field that contains the `id` of the specified document
+          (e.g. the `foo_set` collection contains a document whose `nickname` field
+          contains `someIdentifier`), it is not necessarily the case that this function
+          will consider that to be a reference. It depends upon what the _schema_ says.
+
+    Note: This can be useful for determining whether the specified document can be safely deleted.
+
+    :param document: The document whose incoming references you want to identify
+    :param schema_view: A `SchemaView` bound to the schema
+    :param references: A `ReferenceList` derived from the schema
+    :param finder: A `Finder` bound to the database being scanned
+    :param client_session: A `pymongo.client_session.ClientSession` instance that, if specified, will be used when
+                           searching for referring documents. If a transaction happens to be pending on that session,
+                           the scan will effectively happen on the database as it _would_ exist if that transaction
+                           were to be committed.
+    :return: A list of descriptors of documents that reference the specified document
+    """
+
+    # Initialize a list of descriptors of documents that reference the specified document.
+    referring_document_descriptors = []
+
+    # Get the specified document's `id` and derive its schema class name.
+    document_id = document["id"]
+    document_class_name = derive_schema_class_name_from_document(schema_view, document)
+    if document_class_name is None:
+        raise ValueError(f"Failed to identify schema class of document having `id`: {document_id}")
+
+    # Identify potential references to the specified document, then group them by their source collection names.
+    potential_references_to_document = references.get_by_target_class_name(document_class_name)
+    potential_references_by_source_collection = potential_references_to_document.group_by_source_collection_name()
+
+    # For each source collection name, check each of its potential references.
+    for collection_name, potential_references_in_collection in potential_references_by_source_collection.items():
+        # Make a list of all the distinct `class_uri`-and-`field_name` tuples.
+        #
+        # Note: Since a `Reference` doesn't have a `source_class_uri` attribute (but it does have a
+        #       `source_class_name` attribute), we derive its `class_uri` from that `source_class_name` attribute.
+        #
+        class_uri_and_field_name_tuples: Set[Tuple[str, str]] = set()
+        for potential_reference in potential_references_in_collection:
+            class_uri = translate_schema_class_name_into_class_uri(
+                schema_view=schema_view, schema_class_name=potential_reference.source_class_name
+            )
+            if class_uri is None:
+                raise ValueError(
+                    f"Failed to translate schema class name '{potential_reference.source_class_name}' into class_uri."
+                )
+            class_uri_and_field_name_tuple = (class_uri, potential_reference.source_field_name)
+            class_uri_and_field_name_tuples.add(class_uri_and_field_name_tuple)
+
+        # For each distinct combination of `class_uri` and `field_name`, check whether any documents in this
+        # collection both (a) have a `type` value matching that `class_uri` and (b) have the subject document's
+        # `id` value in the specified field.
+        referring_documents = finder.find_documents_having_type_and_value_in_field(
+            collection_name=collection_name,
+            type_and_field_name_tuples=list(class_uri_and_field_name_tuples),
+            value=document_id,
+            client_session=client_session,
+        )
+
+        # For each referring document, store a descriptor of it.
+        for referring_document in referring_documents:
+            source_class_name = translate_class_uri_into_schema_class_name(
+                schema_view=schema_view,
+                class_uri=referring_document["type"],
+            )
+            document_descriptor = dict(
+                source_collection_name=collection_name,
+                source_class_name=source_class_name,
+                source_document_object_id=referring_document["_id"],
+                source_document_id=referring_document["id"],
+            )
+            referring_document_descriptors.append(document_descriptor)
+
+    return referring_document_descriptors
+
+
 def scan_outgoing_references(
     document: dict,
     schema_view: SchemaView,
-    # TODO: Cache this dictionary, since it is derived from the schema alone.
-    reference_field_names_by_source_class_name: Dict[str, List[str]],
     references: ReferenceList,
     finder: Finder,
-    collection_names: List[str],
     source_collection_name: str,
-    client_session: ClientSession = None,
+    client_session: Optional[ClientSession] = None,
     user_wants_to_locate_misplaced_documents: bool = False,
 ) -> ViolationList:
     r"""
@@ -34,19 +123,17 @@ def scan_outgoing_references(
 
     :param document: The source document from which the references emanate
     :param schema_view: A SchemaView bound to the schema
-    :param reference_field_names_by_source_class_name: Dictionary mapping class names to lists of reference field names
     :param references: A `ReferenceList` derived from the schema
     :param finder: A `Finder` bound to the database being scanned
-    :param user_wants_to_locate_misplaced_documents: Whether the user wants the function to proceed to search illegal
-                                                     collections after failing to find the referenced document among
-                                                     all the legal collections
     :param source_collection_name: Name of collection in which source document resides (this is included in the
                                    violation report in an attempt to facilitate investigation of violations)
     :param client_session: A `pymongo.client_session.ClientSession` instance that, if specified, will be used when
                            searching for referenced documents. If a transaction happens to be pending on that session,
                            the scan will effectively happen on the database as it _would_ exist if that transaction
                            were to be committed.
-    :param collection_names: List of collection names that are described by the schema
+    :param user_wants_to_locate_misplaced_documents: Whether the user wants the function to proceed to search illegal
+                                                     collections after failing to find the referenced document among
+                                                     all the legal collections
     """
 
     # Initialize a list of violations.
@@ -54,14 +141,20 @@ def scan_outgoing_references(
 
     # Get the document's `id` so that we can include it in this script's output.
     source_document_object_id = document["_id"]
-    source_document_id = document["id"] if "id" in document else None
+    source_document_id: Optional[str] = document["id"] if "id" in document else None
 
     # Get the document's schema class name so that we can interpret its fields accordingly.
     source_class_name = derive_schema_class_name_from_document(schema_view, document)
+    if source_class_name is None:
+        raise ValueError(f"Failed to derive schema class name from document having `id`: {source_document_id}")
 
     # Get the names of that class's fields that can contain references.
+    reference_field_names_by_source_class_name = references.get_reference_field_names_by_source_class_name()
     names_of_reference_fields = reference_field_names_by_source_class_name.get(source_class_name, [])
 
+    # Get the names of collections that are described by the schema.
+    collection_names = get_collection_names_from_schema(schema_view=schema_view)
+
     # Check each field that both (a) exists in the document and (b) can contain a reference.
     for field_name in names_of_reference_fields:
         if field_name in document:
@@ -100,6 +193,15 @@ def scan_outgoing_references(
                             )
                         )
 
+                    # Handle the case where the source document does not have an `id`.
+                    #
+                    # Note: As a reminder, according to the NMDC Schema (as of version v11.7.0), documents in the
+                    #       `functional_annotation_agg` collection do not have an `id` field.
+                    #       Reference: https://microbiomedata.github.io/nmdc-schema/FunctionalAnnotationAggMember/
+                    #
+                    if not isinstance(source_document_id, str):
+                        source_document_id = ""
+
                     # Instantiate a `Violation` containing information about this referential integrity violation.
                     violation = Violation(
                         source_collection_name=source_collection_name,
@@ -121,7 +223,6 @@ def scan(
     db: Database,
     schema_view: SchemaView,
     references: ReferenceList,
-    collection_names: List[str],
     names_of_source_collections_to_skip: List[str],
     user_wants_to_locate_misplaced_documents: bool = False,
     console: Console = default_console,
@@ -135,7 +236,6 @@ def scan(
     :param schema_view: A SchemaView bound to the schema with which that database complies
                         (except that it may not be compliant in terms of referential integrity)
     :param references: A `ReferenceList` derived from the schema
-    :param collection_names: List of collection names that are described by the schema
     :param names_of_source_collections_to_skip: List of source collections to skip
     :param user_wants_to_locate_misplaced_documents: Whether the user wants the function to proceed to search illegal
                                                      collections after failing to find the referenced document among
@@ -144,9 +244,6 @@ def scan(
     :param verbose: Whether you want the function to print a higher-than-normal amount of information to the console
     """
 
-    # Get a dictionary that maps source class names to the names of their fields that can contain references.
-    reference_field_names_by_source_class_name = references.get_reference_field_names_by_source_class_name()
-
     # Initialize a progress bar.
     custom_progress = init_progress_bar()
 
@@ -226,10 +323,8 @@ def scan(
                 violations = scan_outgoing_references(
                     document=document,
                     schema_view=schema_view,
-                    reference_field_names_by_source_class_name=reference_field_names_by_source_class_name,
                     references=references,
                     finder=finder,
-                    collection_names=collection_names,
                     source_collection_name=source_collection_name,
                     user_wants_to_locate_misplaced_documents=user_wants_to_locate_misplaced_documents,
                 )