Contextual Conventional Commits

A generic VS Code extension that composes Conventional Commit messages through the built-in Git Source Control interface.

Read the complete documentation.

Unlike flat scope pickers, this extension resolves scopes after the commit type is selected. Repository policy can therefore allow build(npm) while rejecting redundant combinations such as build(build).

Features

• contextual type-to-scope selection;
• reusable named scope groups;
• explicit per-type scopes and exclusions;
• optional or required scopes per type;
• configurable custom-scope entry;
• changed-directory scope inference;
• contextual, type-specific Git trailer suggestions and cautions;
• Conventional Commit formatting and validation;
• breaking-change body and Git trailers;
• multi-repository workspace support;
• no runtime dependencies and no source-code transmission.

Commands

• Git: Compose Contextual Conventional Commit
• Git: Validate Conventional Commit
• Git: Compose and Commit

Example

Given this policy:

{
  "contextualConventionalCommits.scopeGroups": {
    "build-tools": ["docker", "vite"],
    "package-managers": ["npm", "pnpm", "uv"]
  },
  "contextualConventionalCommits.typeScopeMatrix": {
    "build": {
      "groups": ["build-tools", "package-managers"],
      "scopes": ["deps", "packaging"],
      "exclude": ["build", "ci"],
      "allowNone": true,
      "allowCustom": false
    }
  }
}

The extension offers:

build(docker)
build(vite)
build(npm)
build(pnpm)
build(uv)
build(deps)
build(packaging)

It rejects:

build(build)
build(ci)
build(api)

Configuration model

contextualConventionalCommits.types

Defines the available commit types and their descriptions.

contextualConventionalCommits.scopeGroups

Defines reusable named arrays of scopes:

{
  "contextualConventionalCommits.scopeGroups": {
    "components": ["api", "cli", "parser", "server"],
    "platforms": ["linux", "windows", "macos"],
    "ci-providers": ["github-actions", "gitlab", "jenkins"]
  }
}

contextualConventionalCommits.typeScopeMatrix

Maps each type to its contextual scope policy:

{
  "contextualConventionalCommits.typeScopeMatrix": {
    "feat": {
      "groups": ["components"],
      "exclude": ["feat", "feature", "new"],
      "allowNone": true,
      "allowCustom": true
    },
    "ci": {
      "groups": ["ci-providers"],
      "scopes": ["lint", "release", "test"],
      "exclude": ["ci"],
      "allowNone": true,
      "allowCustom": false
    }
  }
}

Rule fields:

contextualConventionalCommits.typeTrailerMatrix

Maps each type to high-value trailer tokens and contextual cautions. The composer lets users add one recommended or custom token and value at a time, remove mistakes, repeat a token when necessary, and finish without writing a CSV list.

Recommended tokens display a concise meaning from contextualConventionalCommits.trailerDescriptions. After selection, the value box shows a token-specific example from contextualConventionalCommits.trailerExamples. Teams can override or add both for their own vocabulary:

{
  "contextualConventionalCommits.trailerDescriptions": {
    "Fixes": "Issue or causal commit whose defect this change corrects",
    "Runbook": "Operational procedure affected by the change"
  },
  "contextualConventionalCommits.trailerExamples": {
    "Fixes": "#321",
    "Runbook": "docs/runbooks/batch-worker.md"
  }
}

{
  "contextualConventionalCommits.typeTrailerMatrix": {
    "fix": {
      "highValue": ["Fixes", "Closes", "Reported-by", "Tested-by"],
      "discouraged": ["Implements-blueprint"]
    },
    "security": {
      "highValue": ["CVE", "GHSA", "Security-impact", "Fixes", "Backport-to"],
      "discouraged": ["Public embargo details before disclosure"]
    }
  }
}

Recommended semantic model

The type answers what kind of change occurred. The scope identifies which package, subsystem, component, platform, or artefact is affected.

Good examples:

feat(api): add batch endpoint
fix(parser): handle escaped names
build(pnpm): update lockfile
ci(github-actions): publish release assets
docs(cli): document authentication options
security(auth): reject replayed authentication tokens

Redundant examples rejected by the default policy:

feat(feature): add export
fix(bug): handle null value
build(build): update tooling
ci(ci): adjust workflow
docs(docs): improve guide

The alphabetized default policy combines types used across Conventional Commits, Angular, Vue, commitlint, semantic-release, Release Please, Conventional Changelog, Atom, and common monorepo and domain workflows. The domain-oriented entries are project extensions rather than built-in Conventional Commits types; projects using a restricted commitlint type-enum must add the extensions they retain. See docs/type-scope-best-practices.md for the source mapping and consolidated scope and trailer guidance.

Development

npm install
npm run check
npm run package

The extension requires VS Code 1.95 or newer.

License