natyoung / contextive

Get on the same page.

Contextive

Contextive is a suite of tools to immerse developers in the language of their users' domains.

Inspiration

Contextive is inspired by the concept of the Ubiquitous Language from the practice of Domain Driven Design (DDD) and is intended to support ubiquitous language management practices on DDD projects.

Even if you're not using Domain Driven Design, Contextive should still be very helpful in any software project where it's important that developers are aligned on the meaning of terms.

By defining terms in a central definitions file, Contextive can surface definitions and usage examples in auto-complete suggestions & hover panels wherever the terms are used - in code (of any language across the stack), comments, config, and documentation (e.g. markdown).

Installation

See our Installation Guide for details on how to install in a few different IDEs, or any IDE that supports the Language Server Protocol.

Officially supported IDEs include:

VsCode

IntelliJ IDEs (e.g. IDEA, except Rider)

Neovim

Helix

Configuration & Usage

See our Usage Guide for details on configuring Contextive, setting up your definitions file, and the various features and options available to you in defining your domain-specific terminology.

Features

The following list is a rough and evolving backlog/roadmap. Checked items are completed, others are not a commitment, just ideas that have been suggested.

• Ubiquitous Language Definition & Storage:
  • Classify terms as aggregates/entities, attributes, commands and events
  • For each term, include a definition, and examples of usage in normal sentences
  • Link terms to each other (e.g. commands to the aggregates/entities they apply to; events to the aggregates/entities that publish them)
  • Define relationships between contexts (e.g. a Context Map definition)
  • Store Ubiquitous Language term definitions in a file in the repository (e.g. yml format)
  • Repository Layouts:
    • Support a monorepo with multiple Bounded Contexts in one repo - identify which paths relate to each Bounded Context
    • Support a Bounded Context distributed across multiple repos (#36)
  • Support aliases of terms, hovering over the alias shows the term definition
  • Add details of the alias in the hover
  • Add ability to define an alias as deprecated and warn as such
  • Support multiline domain vision statements, definitions and usage examples
• IDE Support
  • Visual Studio Code
    • Support single-root workspaces
    • Support multi-root workspaces with a shared definitions file
    • Support multi-root workspaces with a definitions file per root
  • Visual Studio (2019/2022)
  • Eclipse
  • NetBeans
  • JetBrains
  • neovim
  • helix
  • emacs
• Code-editing Features
  • Show the term definitions & usage examples when hovering over the word in the editor
    • Also when the word being hovered over is plural of the defined singular term
    • Also when the word being hovered over is singular of the defined plural term
    • Also when the combined word being hovered over is contains singular or plural of a word in a defined multi-word term
  • Add Ubiquitous Language terms to the auto-complete list
  • Codelens to identify the number of Ubiquitous Language terms in a method or class
  • Problems/warnings if misuse of the Ubiquitous Language - e.g. use of Command/Event and aggregate in the same class or method name when they are not linked, or use of extra words next to an Aggregate that isn't defined
  • In relevant places (e.g. hover), note the use of the term in other contexts to highlight the contrast and ensure clarity of which definition applies in the current context (e.g. 'THIS definition, NOT that other definition that you might have been thinking of')
• Ubiquitous Language Management Features
  • Go To term definition (right-click menu, keyboard shortcut)
  • A UI widget to view the language terms in a TreeView and offer facilities for adding, updating & removing terms
  • Make it easy to add terms to the Ubiquitous Language from existing code e.g. by highlighting and using the right-click menu
• Ubiquitous Language Sharing Features
  • Render definitions into a human readable format - e.g. html, markdown etc.
  • Sync definitions into a cloud storage, e.g. Notion database, or confluence page
  • Above features might be well packaged as a CLI as well as extension features, for running in CI/CD

Contributing

See CONTRIBUTING for details.

Logo

The Contextive logo is based (with extreme gratitude!) on the Bibliophile image from https://undraw.co - an amazing resource of free images and illustrations.

License

This project is licensed under the MIT license. See LICENSE.