Gritql Linter Effect Nx

GritQL Linter for Nx + Effect TypeScript

Instructions

This skill provides GritQL-based linting and refactoring capabilities for TypeScript monorepo codebases, specifically optimized for Nx monorepos with Effect-TS and strict typing practices.

Available Commands

/lint-type-safety - Type Safety Checks

Run all type safety related GritQL patterns.

Patterns executed:

• ban-type-assertions - Detects as any, as T, satisfies operators
• ban-return-types - Detects explicit return types on functions
• ban-ts-ignore - Detects @ts-ignore, @ts-expect-error, @ts-nocheck

Usage:

grit check \
  --pattern ban-type-assertions \
  --pattern ban-return-types \
  --pattern ban-ts-ignore \
  .

Context:

• Detects type assertions that bypass TypeScript's type inference
• Identifies suppression comments that hide bugs
• Violations reference docs/LINTING_POLICY.md for remediation

Remediation:

• Use Schema.decodeUnknown() for external data (Effect-TS)
• Add proper type guards to narrow types
• Fix underlying type errors instead of suppressing them

/lint-effect - Effect-TS Pattern Enforcement

Run all Effect-specific GritQL patterns.

Patterns executed:

• ban-imperative-error-handling-in-effect - Detects Promise primitives, throw, try-catch in Effect
• detect-missing-yield-star - Detects missing yield* in Effect.gen
• detect-unhandled-effect-promise - Detects Effect.tryPromise without typed errors
• enforce-effect-pipe - Detects deeply nested Effect calls (3+ levels)

Usage:

grit check \
  --pattern ban-imperative-error-handling-in-effect \
  --pattern detect-missing-yield-star \
  --pattern detect-unhandled-effect-promise \
  --pattern enforce-effect-pipe \
  .

Context:

• Effect tracks errors in the type system (Effect<A, E, R>)
• Imperative patterns break Effect's typed error tracking
• Missing yield* causes silent bugs (assigns Effect instead of T)

Remediation:

• Use Effect.tryPromise() with { try, catch } for async operations
• Always use yield* when calling Effects in Effect.gen
• Use Effect.pipe() for composition instead of nesting
• Reference ai/skills/effect-service-architect/SKILL.md for remediation patterns

/lint-monorepo - Monorepo Boundary Checks

Run Nx/monorepo boundary violation patterns.

Patterns executed:

• ban-relative-parent-imports - Detects ../../ imports
• enforce-nx-project-tags - Ensures project.json has tags

Usage:

grit check \
  --pattern ban-relative-parent-imports \
  --pattern enforce-nx-project-tags \
  .

Context:

• Monorepo structure enforced via workspace aliases (@org/lib)
• Nx project tags enable module boundary enforcement
• Relative parent imports cross library boundaries incorrectly

Stack Detection:

• Scans for nx.json and project.json files
• Checks for pnpm-workspace.yaml or workspace configuration
• Adjusts enforcement based on detected infrastructure

Remediation:

• Replace ../../lib imports with workspace alias @org/lib
• Add tags to project.json (e.g., ["type:lib", "scope:shared"])

/lint-all - Full Analysis (Default)

Run all 14 GritQL patterns and generate categorized report.

Usage:

grit check .

Stack Detection:

• Nx: Check for nx.json, project.json files
• Effect: Scan for imports from "@effect/*"
• TypeScript: Verify tsconfig.json exists

Report Format:

## GritQL Lint Report

### Type Safety (4 patterns)
- ban-type-assertions: 5 violations (error)
- ban-return-types: 2 violations (error)
- ban-ts-ignore: 0 violations
- prefer-object-spread: 1 violation (warn)

### Effect-TS (4 patterns)
- ban-imperative-error-handling: 3 violations (error)
- detect-missing-yield-star: 1 violation (error)
- detect-unhandled-effect-promise: 0 violations
- enforce-effect-pipe: 2 violations (error)

### Monorepo (2 patterns)
- ban-relative-parent-imports: 4 violations (error)
- enforce-nx-project-tags: 2 violations (warn)

### General (4 patterns)
- ban-default-export-non-index: 0 violations
- ban-push-spread: 1 violation (error)
- enforce-esm-package-type: 0 violations
- enforce-strict-tsconfig: 0 violations

Total: 21 violations (17 error, 4 warn)

/fix-pattern PATTERN_NAME - Apply Pattern Fix

Apply a specific GritQL pattern with dry-run preview and verification.

Workflow:

1. Dry-run: Preview changes before applying

   grit apply --pattern PATTERN_NAME --dry-run .
   

2. Review: Examine the unified diff output
3. Apply: Apply the changes

   grit apply --pattern PATTERN_NAME .
   

4. Verify: Run Biome to verify no new violations

   biome check .
   

Safety Mode:

• Requires confirmation for each file modification
• Shows diff before applying changes
• Reverts on failure if verification fails

Note: Only available for patterns with auto-fix capabilities. Check pattern documentation for fixability.

/analyze-violations - Deep Analysis

Perform comprehensive analysis of violations with contextual information.

For each violation:

• Show surrounding code context (5 lines before/after)
• Identify why pattern triggered
• Suggest refactoring strategy
• Link to pattern file: biome/gritql-patterns/PATTERN_NAME.grit
• Reference documentation:
  • Type safety: docs/LINTING_POLICY.md
  • Effect patterns: ai/skills/effect-service-architect/SKILL.md
  • Type safety cleanup: ai/skills/type-safety-enforcer/SKILL.md

Pattern Categories

Integration Points

With .grit/grit.yaml

Pattern files are referenced via glob pattern:

# .grit/grit.yaml
version: 0.0.1
patterns:
  - biome/gritql-patterns/*.grit

With gritql.nix Module

The existing Home Manager module (modules/home-manager/programs/gritql.nix) automatically:

• Symlinks patterns to ~/.config/grit/patterns (for global grit access)
• Symlinks patterns to ~/.config/biome/gritql-patterns (for biome integration)
• Patterns are available in any workspace via these symlinked paths

With Biome

Patterns are executed via Biome's GritQL integration:

biome check --gritql-patterns ~/.config/biome/gritql-patterns .

Context Awareness

The skill adapts enforcement based on detected stack components:

1. Nx Detection:

   • Checks for nx.json in project root
   • Scans for project.json files in subdirectories
   • Enables monorepo patterns only if Nx detected

2. Effect Detection:

   • Scans for imports from "@effect/*" package
   • Checks for Effect-specific constructs (Effect.gen, yield*, etc.)
   • Enables Effect-specific patterns only if Effect detected

3. Monorepo Detection:

   • Checks for pnpm-workspace.yaml
   • Checks for package.json with workspaces property
   • Enables boundary patterns only if monorepo detected

4. Workspace Alias Suggestions:

   • When detecting ../../ imports in monorepo context
   • Suggests workspace alias based on library location
   • Example: ../../libs/auth → @my-org/auth or similar

Common Workflows

Run All Checks on Nx Monorepo

# Detect stack, run all applicable patterns
grit check .

Fix Type Safety Violations

# 1. First, see what needs fixing
grit check --pattern ban-type-assertions .

# 2. Preview changes
grit apply --pattern ban-type-assertions --dry-run .

# 3. Apply changes
grit apply --pattern ban-type-assertions .

# 4. Refine with type-safety-enforcer skill for complex cases
# Use /skills type-safety-enforcer for systematic cleanup

Enforce Effect-TS Patterns

# Check for Effect violations
grit check --pattern detect-missing-yield-star .

# Analyze violations in context
# Use /analyze-violations for detailed remediation suggestions

# For complex Effect refactoring:
# Use /skills effect-service-architect for full service scaffolding

Monorepo Boundary Enforcement

# Find all relative parent imports
grit check --pattern ban-relative-parent-imports .

# Review violations - each will suggest workspace alias
# Manually update imports based on alias suggestions

# Ensure all projects have tags
grit check --pattern enforce-nx-project-tags .

Documentation References

All violations reference relevant documentation:

• Type Safety: docs/LINTING_POLICY.md - Complete policy on type safety guardrails
• Pattern Details: biome/gritql-patterns/*.grit - Individual pattern rationale and examples
• Effect Remediation: ai/skills/effect-service-architect/SKILL.md - Effect service patterns
• Type Safety Cleanup: ai/skills/type-safety-enforcer/SKILL.md - Systematic type safety elimination
• Structural Refactoring: ai/skills/structural-refactor/SKILL.md - GritQL-based transformations

Verification Checklist

After running fixes:

• TypeScript compilation passes: tsc --noEmit
• Biome validation passes: biome check
• No new GritQL violations introduced
• Tests still pass: bun test (or project-specific test command)
• No broken imports after refactoring
• Workspace aliases correctly configured (if monorepo)

Related Skills

• type-safety-enforcer: Systematically eliminate type holes (as any, !, @ts-ignore)
• effect-service-architect: Scaffold and refactor Effect-based services
• structural-refactor: Perform codebase-wide transformations using GritQL

Converted and distributed by TomeVault — claim your Tome and manage your conversions.