The Rules page at /rules lists all active rules that belong to your account. From here you can create new rules, monitor their status, edit existing rules, and archive rules that are no longer needed.
What a rule is
A rule is a self-contained, versioned analysis prescription. It consists of a .cgr file (the actual rule logic written in the CodeCharter DSL) and an optional spec file (test examples that prove the rule detects what it should). Each rule has an immutable slug, an optional display name, and a default severity (Info, Warning, or Error).
Rules are versioned independently and included in CI runs via profiles. Until a rule is published there is no SemVer version and no CI pipeline can reference it.
The rules list
Each row in the table shows:
- Slug — the immutable URL-safe identifier and optional display name.
- Last version — the most recently published SemVer version. Unpublished rules show a dash.
- Severity — the default severity the rule emits when a finding is raised (Info, Warning, or Error).
- Status — either a Draft pill when the rule has an unpublished draft, or a Published pill with the publish date.
- In profiles — the number of published profile versions that reference this rule. Click the badge to open the rule detail page.
Filtering and searching
The filter bar lets you narrow the list by free-text search (applied to slug and display name), severity, status, and tags. The search input is debounced by 300 ms so the list refreshes while you type without generating unnecessary requests.
The No spec toggle filters to rules that have no test specification yet — useful for tracking authoring progress.
Creating a rule
Click New rule in the top right to open the creation form. You choose a slug (immutable after creation), an optional display name, and a default severity. The rule starts without any published version and without a draft.
Editing a rule
Open the kebab menu (⋮) on any rule row and choose Edit to open the rule editor. The editor is split into two halves:
The left editor contains the .cgr file — the actual rule logic written in the CodeCharter DSL. Syntax errors are underlined inline. You can edit the file freely; changes are saved automatically as a draft.
The right spec editor contains the test specification, written in Markdown: code samples are grouped under ## hits and ## misses headings into positive and negative examples that prove the rule detects the right things. A Preview toggle in the pane header renders the Markdown. Rules that have no spec yet are easy to find via the No spec filter in the rules list.
The AST inspector lives in the AST tab of the collapsible tools panel to the right of the editors. It shows the C# syntax tree of the sample code in the currently selected spec case, which helps you verify that your query targets the right elements.
Spec run and debugging
Running the spec
Click Run specs in the editor to execute all spec cases against the current saved revision — save the draft first so the run picks up your latest changes. The result appears in the bottom panel: each test case gets a status pill (Passed, Failed, Error, or Timeout).
Trace drawer
Click a failed or errored test case row to open the trace drawer. Its Trace tab shows a tree of evaluation steps with a pass/fail mark and detail for each step, and the Diff tab compares the expected against the actual result, so you can see why a finding was or was not triggered.
Understanding errors
Common causes of spec failures:
- Query matches the wrong elements: The query returns a broader or narrower set than expected. Use the AST inspector to check which elements actually match. For example, if you want to flag a specific method but the query fires on the declaring type, adjust the root collection from
TypestoMethods. - Missing negative examples: Without counter-examples the rule may inadvertently match too broadly.
Editing rules in VS Code
For longer editing sessions you can take the current draft out of the portal, work on it in VS Code, and send the result back as a draft.
Prerequisites
- The CodeCharter VS Code extension is installed. It registers the link handler that receives the draft and provides the push command.
- The extension setting
codecharter.portalBaseUrlpoints to the portal you are using. The default ishttps://codecharter.tools; you only need to change it if you work against a different portal address. - Your browser is allowed to open
vscode://links (most browsers show a confirmation prompt on first use).
You do not sign in to the portal from VS Code. The handoff link carries a short-lived access token that is valid only for this one rule and expires after five minutes.
Opening a draft in VS Code
In the rule editor, open the overflow menu (⋮) and choose Open in VSCode. The action becomes available once the draft has been saved at least once; a brand-new, never-saved draft cannot be handed off yet.
VS Code opens the current draft in two editors side by side: the .cgr source on the left and the spec (Markdown) next to it. If VS Code asks for the rule slug, enter the slug exactly as shown in the portal. A notification confirms which rule and draft revision were loaded and reminds you of the push command.
Editing and testing locally
Edit the source and spec in VS Code with full DSL support (highlighting, completion, inline validation). The two handoff editors start out as unsaved in-memory documents. Spec tests run against files on disk, so to test locally, save a copy of the contents as <name>.cgr and <name>.spec.md next to each other and run codecharter test on them, or use the extension's spec commands on the saved files.
Push to portal
When you are done, run the CodeCharter: Push to portal command. It sends the current contents of the two handoff editors back to the portal, where they replace the rule's draft.
The push only ever updates the draft. It never publishes a version: you review the result in the portal rule editor, run the specs there, and publish as usual (see the Publishing section below). After a successful push you can keep editing in VS Code and push again.
Conflicts and expired links
If the draft changed on the portal side after you pulled it (for example because someone edited it in the portal editor, which autosaves), the push is rejected and VS Code shows a "draft changed elsewhere" warning. Nothing is overwritten: the portal keeps its current draft. Pull the draft again via Open in VSCode and re-apply your changes to the fresh copy.
If the access token from the handoff link has expired, the push fails with a token-expired message. Use Open in VSCode in the portal again to start a fresh handoff.
Publishing
Once the draft passes all spec tests you can publish a new version.
Choosing a SemVer
Click Publish. The form suggests the next patch version (e.g. 1.0.0 for a new rule or 1.2.4 after 1.2.3). You can choose Minor or Major when the change warrants it, or enter a custom version number. SemVer follows the usual convention: Patch for bug fixes and minor adjustments, Minor for new detection features without breaking changes, Major for breaking changes. If the draft is identical to the last published content, the form shows a warning before you publish a no-op version.
Release notes
The publish form includes a required Release notes field (Markdown, up to 4 KB); publishing is blocked while it is empty. The notes are stored with the published version. Keep them short and to the point — one sentence describing what changed and why is usually enough.
Follow-up action: profile bulk-publish
After publishing, the portal shows a dialog listing any profiles that still reference an older version of this rule. Pick the profiles you want to update and click Create drafts: each selected profile receives a new draft with the updated rule reference. You then review and publish each profile draft as usual. This is the standard way to roll out a new rule version to CI pipelines.
Archiving a rule
Open the kebab menu (⋮) on any rule row and choose Archive. A confirmation dialog points out that existing published versions stay resolvable via lockfiles. After archiving, the rule no longer appears in the active list.
Slugs are immutable. If you need a different slug, create a new rule with the desired name and archive the old one.
Unarchiving
Archived rules can be reactivated from the Archive tab. Open the tab at /rules/archive, find the rule, and choose Unarchive from the kebab menu. The rule reappears in the active list and a new draft or publication is then possible.
The Archive tab
Archived rules are accessible from the Archive tab at the top of the page (/rules/archive).
Versions
Version history
Choose View versions in the kebab menu to open the rule detail page, then switch to the Version history tab. It shows every published version with its SemVer number, publish date, engine version, and spec status. Yanked versions carry a yanked badge.
Snapshot view
Click the Snapshot action in a version row to open its snapshot: the exact .cgr file and spec as they looked at the time of publication. Snapshots are immutable — you can read but not edit them.
Diffing versions
Open a version's snapshot and click Diff to another version… to pick the version to compare against. The diff view shows both versions side by side in three tabs — Source (.cgr), Spec (.spec.md), and Metadata — and lets you switch the From and To versions at any time. This gives you an immediate overview of what changed between two releases.
Predicate catalog in the editor
When you write a new .cgr file or edit an existing one, the rule editor offers the predicate catalog in the tools panel to the right of the code area. It lists the DSL operations you can use in queries, grouped by category (String, Collection, Operator), each with its signature, a short description, and a usage example. You do not need to memorize the catalog.
Opening and filtering the catalog
Open the Predicates tab in the collapsible tools panel on the right to show the catalog. A search field at the top filters entries by name, signature, description, or category. Clicking an entry expands its details; the Insert into editor button inserts the usage example into the .cgr editor.
Root collections at a glance
| Root | Contains | Typical entry point |
|---|---|---|
Types |
TypeModel |
All classes, structs, interfaces, enums |
Methods |
MethodModel |
All methods across all types |
Properties |
PropertyModel |
All properties |
Fields |
FieldModel |
All fields |
SyntaxIssues |
SyntaxIssue |
Pre-analysed syntax patterns |
For the full property list of each model type see Predicate catalog.
Snippet palette
The snippet palette provides ready-made DSL building blocks that you insert into the editor with a single click, organised by category.
Opening the palette
Click the Snippets button in the toolbar of the source pane (or press Ctrl+Shift+S) to open the snippet palette. Snippets are grouped by category: rule skeletons, predicates, and spec cases.
Inserting snippets
Clicking a snippet name shows a preview; the Insert snippet button then inserts the template at the current cursor position. The template contains pre-filled placeholders that you can jump through with Tab and replace immediately.
Custom snippets
The portal does not store user-defined snippets. If you want to reuse a pattern you wrote, copy the relevant DSL block from an existing rule into the new rule's editor and adjust it as needed.