Skip to content

Add What It Does rule (behaviour scanner for AI-edited code) #351

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rolfe099-sketch wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add What It Does rule (behaviour scanner for AI-edited code) #351

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,6 +263,7 @@ By adding selected `.mdc` files to `.cursor/rules/`, you can use these rules dir
- [TypeScript Code Convention](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/typescript-code-convention-cursorrules-prompt-file.mdc) - TypeScript development with code convention integration.
- [VSCode Extension (Electron/TypeScript)](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/vscode-extension-dev-typescript-cursorrules-prompt-file.mdc) - VSCode extension development with Electron and TypeScript integration.
- [Web App Optimization](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/web-app-optimization-cursorrules-prompt-file.mdc) - Web app development with optimization integration.
- [What It Does (Behaviour Scanner)](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/what-it-does.mdc) - Comparing an application's behaviour before and after an edit — entry points, the data each one touches, and whether an authorization check disappeared. Next.js App Router and Cloudflare Pages Functions.

@coderabbitai coderabbitai Bot Aug 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Keep the catalog alphabetically ordered.

What It Does is followed by Ankra CLI, so this addition is not alphabetically placed. Move What It Does after Web App Optimization, or move Ankra CLI before AI Agent Specialist.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` at line 266, Reorder the README catalog alphabetically by moving
the “What It Does (Behaviour Scanner)” entry after “Web App Optimization” or
moving “Ankra CLI” before “AI Agent Specialist,” while preserving the existing
entry text and links.

- [Ankra CLI (Kubernetes Cluster Management)](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/ankra-cli.mdc) - Ankra CLI development with Kubernetes cluster management integration.

### Language-Specific
Expand Down
76 changes: 76 additions & 0 deletions rules/what-it-does.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
---
description: "Check what your edits actually changed about an application's behaviour — endpoints, what they read, write and delete, and whether a guard disappeared — using the what-it-does scanner. Apply when editing routes, server actions, middleware, or the code they reach."
globs: **/app/**/route.ts, **/app/**/route.js, **/app/**/page.tsx, **/actions.ts, **/actions.js, **/middleware.ts, **/middleware.js, **/functions/**/*.ts, **/functions/**/*.js

@coderabbitai coderabbitai Bot Aug 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== repo files matching rule name =="
fd -a 'what-it-does\.mdc|what-it-does' . | sed 's#^\./##' || true

echo
echo "== rules/what-it-does.mdc with numbering =="
if [ -f rules/what-it-does.mdc ]; then
  cat -n rules/what-it-does.mdc | sed -n '1,120p'
fi

echo
echo "== all .mdc rule files =="
git ls-files '*.mdc' | sed -n '1,80p' || true

echo
echo "== search for globs/alwaysApply in mdc files =="
rg -n "globs:|alwaysApply:" -g '*.mdc' . || true

Repository: PatrickJS/awesome-cursorrules

Length of output: 46453

🌐 Web query:

Cursor context rules globs automatically apply rule rules files globs documentation

💡 Result:

In Cursor, context rules are configured using.mdc (Markdown Cursor) files located in the.cursor/rules/ directory [1][2][3]. These files use YAML frontmatter to control how and when rules are applied through the alwaysApply, description, and globs properties [1][4][5]. Key details regarding context rules and glob patterns: 1. Rule Format: Rules must be stored as.mdc files in the.cursor/rules/ directory [2][5][6]. Plain.md files in this directory are ignored because they lack the necessary frontmatter [1][7][6]. 2. Glob Patterns: The globs field is used to scope a rule to specific files or directories [1][3]. When you define globs, the rule becomes "Auto-Attached," meaning it is automatically included in the AI context when a file matching the pattern is referenced or edited [1][3][7]. 3. Glob Syntax: - * matches any single file name segment [1][6]. - matches any number of directories (recursive) [1][6]. - Patterns are provided as a comma-separated string (e.g., globs: src//.ts, src//.tsx) [1][7]. - You can use the! prefix to exclude specific patterns [4]. 4. Application Logic: - Always Apply: If alwaysApply is set to true, the rule is included in every conversation, ignoring globs and descriptions [1][7][5]. - Auto-Attached: If alwaysApply is false and globs are provided, the rule triggers when matching files are in the AI context [1][7][5]. - Agent-Requested: If alwaysApply is false, globs are omitted, and a description is provided, the AI agent pulls in the rule when it determines the rule is relevant to the current conversation [1][7][5]. - Manual: If none of the above are set, the rule is only included if you @-mention it explicitly [1][7][5]. The previous single-file.cursorrules system is considered deprecated in favor of this directory-based.mdc approach, which allows for more granular, path-specific rule application [2][3][4].

Citations:

🌐 Web query:

what-it-does CLI supported entry points Next.js page.js page.jsx middleware proxy.js route files

💡 Result:

There is no standard CLI tool named "what-it-does" in the Next.js ecosystem. It is likely that this name refers to either a generic placeholder for "what a CLI does" or is a misidentification of other tools. If you are looking for information on how the official Next.js CLI handles entry points and routing files, here is a summary of how Next.js operates: Next.js CLI Entry Points The official Next.js CLI (next) manages the development, building, and serving of your application [1][2]. It does not operate by manually scanning specific entry points like proxy.js; instead, it uses a file-system-based routing convention [3][4]. Supported File Conventions Next.js automatically discovers and handles the following files within your app (or pages) directory to define your application's behavior [3][4]: page.js / page.jsx: These are the primary entry points for UI routes. They define the content that renders for a given path [3][4]. route.js: Used for creating Route Handlers (API endpoints) in the app directory. Note that you cannot have a route.js file at the same segment level as a page.js file [3][4]. middleware.ts / middleware.js: Defined at the root level of your project, middleware runs before a request is completed, allowing you to intercept, rewrite, or redirect requests globally across your application [5]. proxy.js: There is no native Next.js file convention named proxy.js. Request interception is handled via Middleware or custom server configurations (e.g., in a Node.js custom server setup) [5][6]. If you are using a tool that you believe is named "what-it-does," it may be a specific third-party utility, a misinterpreted MCP (Model Context Protocol) tool—such as the Next.js DevTools MCP, which uses an "index" and "call" structure [7][8]—or a confusion with custom build tools or diagnostic scripts [9]. If you have access to the source code or the package name, you can confirm its function by checking its package.json or associated documentation [7][10].

Citations:

🌐 Web query:

Next.js middleware file convention proxy.js proxy.ts renamed middleware documentation

💡 Result:

In Next.js 16 (released October 2025), the middleware.ts (or .js) file convention was officially deprecated and renamed to proxy.ts (or .js) [1][2][3]. This change was implemented to clarify the purpose of the feature and avoid confusion with the common software engineering term "middleware" (e.g., Express.js middleware), as the feature functions as a network boundary proxy [1][2][4]. While the terminology and filename have changed, the core functionality remains the same: it allows you to run code on the server before a request is completed to perform tasks such as redirects, rewrites, and header modifications [1][4]. Key details regarding the migration and usage include: File Convention: The file should be placed in the project root or inside the src directory, at the same level as the app or pages folders [1][4]. Function Naming: The exported function previously named middleware must be renamed to proxy [2][3]. Configuration: Any configuration flags that previously used "middleware" in their names (e.g., skipMiddlewareUrlNormalize) have been updated (e.g., skipProxyUrlNormalize) [3]. Runtime: Unlike the previous middleware implementation, proxy.ts defaults to the Node.js runtime [1][3]. Migration: Next.js provides an official codemod to automate this migration, which can be run using the following command [2][3]: npx @next/codemod@canary middleware-to-proxy. This codemod automatically renames the file, updates the exported function name, and handles associated configuration changes [1][2]. Documentation for the new proxy.ts convention can now be found in the official Next.js API reference [1][4].

Citations:

Broaden or qualify the auto-attachment scope.

Since alwaysApply is off, these globs determine when Cursor attaches this rule. Add supported entry points so editors match the supported behavior: Next API routes also use page.js, page.jsx, route.js, and route.jsx; app-directory pages also use page.js/page.jsx and page.ts; and Next now uses proxy.ts/proxy.js for middleware. Add patterns for those files, or update the description to state this narrower coverage.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@rules/what-it-does.mdc` at line 3, Broaden the glob list in the rule metadata
to include the supported Next entry points: page.js, page.jsx, page.ts,
route.jsx, and proxy.ts/proxy.js alongside the existing patterns. Keep the
current app, actions, functions, and middleware coverage intact.

alwaysApply: false
---

# Checking what you changed with what-it-does

`what-it-does` is an MIT-licensed CLI that reads a Next.js App Router or
Cloudflare Pages Functions project without executing it and reports its entry
points — pages, endpoints, form actions — with the effects of each: the tables
it reads, writes or deletes from, payment calls, outbound email. It runs
locally and makes no network calls. On an unsupported framework it says so
rather than guessing.
Comment on lines +9 to +14

@coderabbitai coderabbitai Bot Aug 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

curl -fsSL 'https://raw.githubusercontent.com/rolfe099-sketch/what-it-does/main/README.md' |
  rg -n -C 2 'not on this list|warn|unsupported'

Repository: PatrickJS/awesome-cursorrules

Length of output: 397

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== rules/what-it-does.mdc lines 1-40 =="
sed -n '1,40p' rules/what-it-does.mdc

echo
echo "== README upstream broader context =="
curl -fsSL 'https://raw.githubusercontent.com/rolfe099-sketch/what-it-does/main/README.md' | sed -n '85,105p'

Repository: PatrickJS/awesome-cursorrules

Length of output: 2840

Correct the unsupported-framework limitation.

what-it-does silently omits unsupported frameworks instead of warning; don’t present this as an explicit scan result. Use wording such as: unsupported frameworks and runtime-resolved code may be omitted; verify framework support before relying on the report.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@rules/what-it-does.mdc` around lines 9 - 14, Update the description around
what-it-does to state that unsupported frameworks and runtime-resolved code may
be omitted, and advise users to verify framework support before relying on the
report. Remove the claim that unsupported frameworks are explicitly identified
rather than guessed.


## When to use it

A code diff shows which lines moved. It does not show that an endpoint stopped
checking who was asking, or that the last writer to a table is gone and the
table will now go stale. Those are behaviour changes that survive review
because nothing in the diff looks alarming — so compare behaviour before and
after any edit to server-side code.

## The loop

Before editing server-side code, record the current behaviour:

```bash
npx what-it-does --json > .what-it-does/before.json
```

After the edits are complete, compare and read the result:

```bash
npx what-it-does --json > .what-it-does/after.json
Comment on lines +29 to +35

@coderabbitai coderabbitai Bot Aug 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Create .what-it-does/ before redirecting output.

On a clean project, the shell opens .what-it-does/before.json before npx starts. If the directory does not exist, line 29 fails with No such file or directory.

Proposed fix 
+mkdir -p .what-it-does
 npx what-it-does --json > .what-it-does/before.json
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
npx what-it-does --json > .what-it-does/before.json
```
After the edits are complete, compare and read the result:
```bash
npx what-it-does --json > .what-it-does/after.json
mkdir -p .what-it-does
npx what-it-does --json > .what-it-does/before.json
After the edits are complete, compare and read the result:
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@rules/what-it-does.mdc` around lines 29 - 35, Update the instructions in the
what-it-does workflow to create the .what-it-does directory before redirecting
output to before.json or after.json, ensuring both commands work in a clean
project.

npx what-it-does diff .what-it-does/before.json .what-it-does/after.json
```

The comparison is in behaviour, not in lines:

```
DELETE /api/projects/[id]
− No longer: Checks who is asking
! 1 new thing worth checking
```

## Rules for using it

- **Surface what it flags. Do not silently act on it.** A finding can be a
false alarm — a guard may live behind an import the scanner could not
follow — and the report states what would make each one wrong. Tell the
user what it said and let them decide.
- **Skip it for changes that cannot alter behaviour**: styling, copy,
comments, tests, documentation, configuration nothing branches on. Running
it on a CSS change wastes a step and teaches everyone to ignore the output.
- **Absence of a finding is not proof.** The scanner reads code without
executing it, so anything reached through a name chosen at runtime is
invisible to it. It says so itself rather than implying coverage it does
not have.
- Add `.what-it-does/` to `.gitignore`; the snapshots are local scratch.

## Other commands

```bash
npx what-it-does # scan here, write and open the HTML report
npx what-it-does ../other-app # scan somewhere else
npx what-it-does --no-code # omit source excerpts, for a shareable report
npx what-it-does agent # write this instruction into CLAUDE.md / AGENTS.md
npx what-it-does diff a.json b.json --fail-on-new # exit 1 on a new finding, for CI
```

The report is a single self-contained HTML file: entry points ranked by
consequence, a walkthrough of each, a dependency map, and a timeline once two
scans exist.

Source: https://github.com/rolfe099-sketch/what-it-does
Loading