Sókrates Wiki

Sets App Type Safety and Linting Remediation

3 min read

Sets App Type Safety and Linting Remediation

Summary

A comprehensive technical debt reduction process focused on resolving 24 type diagnostics and 27 linting issues within the sets_app component of the Grimoire project. This effort involved migrating the type-checking infrastructure from Pyright to Astral’s ty, enforcing LiteralString safety for Neo4j queries, and refactoring core decorators to comply with strict type constraints.

Details

The remediation process was initiated to achieve a zero-diagnostic baseline for the sets_app codebase, ensuring high reliability for the knowledge graph API. The work was tracked via Linear tickets SOK-80/SOK-69 (Type Errors) and SOK-78/SOK-70 (Legacy Code Removal).

Type Checker Migration to ty

The project transitioned to ty (version 0.0.25), a type checker from Astral. This migration necessitated a global update of suppression comments, as ty utilizes the syntax # ty: ignore[rule-name] rather than the standard # type: ignore. Configuration for the tool is centralized in the [tool.ty] section of pyproject.toml. During the migration, an attempt to use [[tool.ty.overrides]] for specific files caused a bug where module exports became unresolved; this was resolved by removing the overrides in favor of rule-level suppression or code refactoring.

Core Decorator Refactoring

The file sets_app/src/sets/core/decorators.py underwent a full rewrite to address systemic typing issues. Because ty correctly identifies that Callable[P, T] does not guarantee a __name__ attribute, a safety helper was introduced:

def _func_name(func: Callable[..., Any]) -> str:
    """Safely extract function name from any callable."""
    return getattr(func, "__name__", repr(func))

The with_session decorator was also updated to handle asynchronous execution correctly by using cast("Callable[..., Awaitable[T]]", func) when awaiting callables in a typed context. Stale suppression comments were purged, and __signature__ assignments were updated to use rule-specific ty: ignore[unresolved-attribute] markers.

Neo4j Query Safety and LiteralString

To prevent Cypher injection and maintain architectural constraints, the project enforced the use of LiteralString for query construction:

  • patterns.py: Methods in NodePattern, RelationshipPattern, and PatternBuilder were updated to return LiteralString via cast("LiteralString", "".join(parts)).
  • builder.py: The where() method signature was modified to accept LiteralString | str, ensuring that dynamically generated conditions are safely handled by the Neo4j driver.

Domain and Infrastructure Fixes

  • Union Types: In memory.py, access to msg.content was guarded with getattr(msg, "content", None) to accommodate Pydantic v2 discriminated unions where certain variants (e.g., specific observation types) do not possess a content field.
  • Protocols: In strategies.py, the @dataclass decorator was removed from the SearchStrategy(Protocol) definition, as Python’s typing rules prohibit Protocols from being dataclasses.
  • Service Layer: In confluence_connector_service.py, unresolved references were fixed (e.g., correcting labels to page_labels), and raw dictionaries were replaced with the structured ServiceErrorDetails model.
  • Linting: 13 instances of the (str, Enum) pattern were upgraded to StrEnum (Python 3.11+), and various import ordering and unused argument issues were resolved using ruff.

Operational Constraints

The remediation session established critical workflow constraints for the Sokrates project:

  1. Prohibition of sed: Direct use of sed on source files is banned after it caused f-string corruption and file truncation.
  2. Bulk Replace Limits: Automated bulk replacements are restricted to five or fewer instances to prevent unintended side effects.
  3. Tooling: All code modifications must be performed via the Edit tool to maintain context and syntax integrity.

Graph View