codelaw-rules-data 0.2.0__py3-none-any.whl

codelaw_rules_data/rules/json/package-scripts-sorted.md

@@ -0,0 +1,53 @@
+---
+id: json/package-scripts-sorted
+title: "package.json scripts are sorted by name"
+languages: [json]
+files: ["**/package.json"]
+fix: auto
+stability: preview
+since: 0.1.0
+---
+
+The `scripts` of a `package.json` are in name order. A `pre<name>` or `post<name>` script sorts next to the `<name>` script it hooks into.
+
+**Why:** A sorted list is quicker to scan and gives smaller diffs when scripts are added; npm runs scripts by name, so their order means nothing to it.
+
+```codelaw
+native: json/package-scripts-sorted
+```
+
+## Examples
+
+### JSON
+
+#### Don't
+
+```json path=package.json
+{
+  "name": "app",
+  "scripts": {
+    "test": "vitest",
+    "build": "tsc",
+    "pretest": "npm run build",
+    "lint": "codelaw check"
+  }
+}
+```
+
+#### Do
+
+```json path=package.json
+{
+  "name": "app",
+  "scripts": {
+    "build": "tsc",
+    "lint": "codelaw check",
+    "pretest": "npm run build",
+    "test": "vitest"
+  }
+}
+```
+
+## Notes
+
+Names compare by Unicode code point. A `scripts` object that uses `npm-run-all`, `run-s` or `run-p` is left alone: those runners expand patterns such as `build:*` in the order the scripts are written, so sorting would change what runs. A `scripts` object with comments in it is reported without a fix, because the comments would stay behind while the scripts move.

codelaw_rules_data/rules/json/tsconfig-schema.md

@@ -0,0 +1,59 @@
+---
+id: json/tsconfig-schema
+title: "tsconfig.json matches its schema"
+languages: [json]
+files: ["**/tsconfig.json", "**/tsconfig.*.json"]
+fix: manual
+fix_reason: "a misspelt or misshapen option has several possible meanings; the author picks the one they intended"
+stability: preview
+ported_from: [schemastore/tsconfig.json]
+since: 0.1.0
+---
+
+A `tsconfig.json` matches SchemaStore's schema for it: every compiler option is one TypeScript knows, with a value of the type it takes.
+
+**Why:** `tsc` reports an unknown option only when it runs, and many editors and bundlers that read `tsconfig.json` skip it silently, so a misspelt `"stirct": true` leaves the project less strict than it looks.
+
+```codelaw
+target: $
+assert: { schema: schemas/tsconfig }
+message: "$ERROR"
+```
+
+## How to fix
+
+1. Read the message: it names the option and what the schema expects, and suggests the option meant when the name is misspelt.
+2. Correct the name or the value; remove an option TypeScript no longer has.
+3. Run `codelaw check` on the file again until it is clean.
+
+## Examples
+
+### JSON
+
+#### Don't
+
+```json path=tsconfig.json
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "stirct": true,
+    "noEmit": "true"
+  }
+}
+```
+
+#### Do
+
+```json path=tsconfig.json
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "strict": true,
+    "noEmit": true
+  }
+}
+```
+
+## Notes
+
+The schema is SchemaStore's `tsconfig.json` schema, shipped with the pack in `data/schemas/tsconfig.json` with its descriptions removed; nothing is fetched. Comments and trailing commas are allowed, as `tsc` allows them. `oneOf` is read as `anyOf`.

codelaw_rules_data/rules/json/tsconfig-strict.cases.md

@@ -0,0 +1,57 @@
+# json/tsconfig-strict — edge cases
+
+### case: extends a base config
+
+```json
+{
+  "extends": "@tsconfig/node22/tsconfig.json",
+  "compilerOptions": { "outDir": "dist" }
+}
+```
+
+```expect
+(none)
+```
+
+### case: strict turned off
+
+```json
+{
+  "compilerOptions": {
+    "strict": false
+  }
+}
+```
+
+```expect
+3:15 json/tsconfig-strict
+```
+
+```fixed
+{
+  "compilerOptions": {
+    "strict": true
+  }
+}
+```
+
+### case: no compilerOptions
+
+```json
+{
+  "include": ["src"]
+}
+```
+
+```expect
+1:1 json/tsconfig-strict
+```
+
+```fixed
+{
+  "compilerOptions": {
+    "strict": true
+  },
+  "include": ["src"]
+}
+```

codelaw_rules_data/rules/json/tsconfig-strict.md

@@ -0,0 +1,45 @@
+---
+id: json/tsconfig-strict
+title: "tsconfig.json turns on strict mode"
+languages: [json]
+files: ["**/tsconfig.json", "**/tsconfig.*.json"]
+fix: suggest
+fix_reason: "turning on strict mode can surface type errors the code then has to fix"
+stability: preview
+since: 0.1.0
+---
+
+A `tsconfig.json` sets `"strict": true` in `compilerOptions`. A config that `extends` another and doesn't set `strict` itself is left alone, since it may inherit it.
+
+**Why:** Strict mode turns on the checks that catch `null` and `undefined` mistakes and implicit `any`; without it the compiler lets most of those bugs through.
+
+```codelaw
+native: json/tsconfig-strict
+```
+
+## Examples
+
+### JSON
+
+#### Don't
+
+```json path=tsconfig.json
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "nodenext"
+  }
+}
+```
+
+#### Do
+
+```json path=tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "es2022",
+    "module": "nodenext"
+  }
+}
+```

codelaw_rules_data/rules/md/commands-show-output.cases.md

@@ -0,0 +1,14 @@
+# md/commands-show-output — edge cases
+
+### case: output shown
+
+````md
+```sh
+$ node --version
+v22.11.0
+```
+````
+
+```expect
+(none)
+```

codelaw_rules_data/rules/md/commands-show-output.md

@@ -0,0 +1,39 @@
+---
+id: md/commands-show-output
+title: "No $ before shell commands that show no output"
+languages: [markdown]
+fix: auto
+stability: preview
+ported_from: [markdownlint/MD014]
+since: 0.1.0
+---
+
+A code block in which every line is a command starting with `$` drops the `$`. A block that also shows output keeps it, since the `$` then tells commands from output.
+
+**Why:** Readers copy commands straight from the block, and a pasted `$` makes every one of them fail.
+
+```codelaw
+native: md/commands-show-output
+```
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+```sh
+$ npm install
+$ npm test
+```
+````
+
+#### Do
+
+````md
+```sh
+npm install
+npm test
+```
+````

codelaw_rules_data/rules/md/descriptive-link-text.md

@@ -0,0 +1,41 @@
+---
+id: md/descriptive-link-text
+title: "Link text says where the link goes"
+languages: [markdown]
+fix: manual
+fix_reason: "describing the target needs the author"
+stability: preview
+options:
+  prohibited_texts: { type: "string[]", default: ["click here", "here", "link", "more"], description: "link texts that say nothing about the target, compared ignoring case and punctuation" }
+ported_from: [markdownlint/MD059]
+since: 0.1.0
+---
+
+A link's text is not a generic phrase such as "click here", "here", "link" or "more".
+
+**Why:** Screen-reader users often jump from link to link, hearing only the link text; "here" tells them nothing.
+
+```codelaw
+native: md/descriptive-link-text
+```
+
+## How to fix
+
+1. Say in a few words what the link leads to.
+2. Make those words the link text.
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+For details, click [here](docs/setup.md).
+````
+
+#### Do
+
+````md
+For details, see [the setup guide](docs/setup.md).
+````

codelaw_rules_data/rules/md/fence-language.md

@@ -0,0 +1,47 @@
+---
+id: md/fence-language
+title: "Fenced code blocks name their language"
+languages: [markdown]
+fix: manual
+fix_reason: "which language the code is in can't always be told from the code"
+stability: preview
+ported_from: [markdownlint/MD040]
+since: 0.1.0
+---
+
+A fenced code block names its language after the opening fence: ` ```ts `, ` ```sh `, or ` ```text ` for plain output.
+
+**Why:** The language drives syntax highlighting, and lets tools — codelaw's `lint_code_blocks` among them — check the code inside.
+
+```codelaw
+match:
+  kind: fenced_code_block
+  not:
+    has: { kind: info_string }
+message: "Name the code's language after the opening fence, or `text` for plain output"
+```
+
+## How to fix
+
+1. Work out what the block holds.
+2. Add its language after the opening fence, or `text` when it is plain output.
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+```
+npm install codelaw
+```
+````
+
+#### Do
+
+````md
+```sh
+npm install codelaw
+```
+````

codelaw_rules_data/rules/md/first-line-heading.cases.md

@@ -0,0 +1,28 @@
+# md/first-line-heading — edge cases
+
+### case: HTML title and leading comment
+
+````md
+<!-- generated -->
+<h1 align="center">Tool</h1>
+
+Text.
+````
+
+```expect
+(none)
+```
+
+### case: front matter title
+
+````md
+---
+title: Tool
+---
+
+Text.
+````
+
+```expect
+(none)
+```

codelaw_rules_data/rules/md/first-line-heading.md

@@ -0,0 +1,46 @@
+---
+id: md/first-line-heading
+title: "A document starts with its title heading"
+languages: [markdown]
+fix: manual
+fix_reason: "the title text needs the author"
+stability: preview
+options:
+  level: { type: "integer", default: 1, description: "the level of the title heading" }
+  allow_preamble: { type: "boolean", default: false, description: "allow text before the title heading" }
+ported_from: [markdownlint/MD041]
+since: 0.1.0
+---
+
+The first block of a document, after any front matter and HTML comments, is a level-1 heading — Markdown, or an HTML `<h1>`. A front matter `title:` counts as the heading.
+
+**Why:** The first heading names the document for readers, search results and tools that build navigation from it.
+
+```codelaw
+native: md/first-line-heading
+```
+
+## How to fix
+
+1. Write a heading that names the document.
+2. Put it first, above any introduction.
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+This tool formats code.
+
+# Formatter
+````
+
+#### Do
+
+````md
+# Formatter
+
+This tool formats code.
+````

codelaw_rules_data/rules/md/heading-increment.cases.md

@@ -0,0 +1,61 @@
+# md/heading-increment — edge cases
+
+### case: front matter title
+
+````md
+---
+title: Guide
+---
+
+### Setup
+````
+
+```expect
+5:1 md/heading-increment
+```
+
+````fixed
+---
+title: Guide
+---
+
+## Setup
+````
+
+### case: subsections move with the fixed heading
+
+````md
+# A
+
+### B
+
+#### C
+
+## D
+````
+
+```expect
+3:1 md/heading-increment
+```
+
+````fixed
+# A
+
+## B
+
+### C
+
+## D
+````
+
+### case: first heading may start deep
+
+````md
+## A
+
+### B
+````
+
+```expect
+(none)
+```

codelaw_rules_data/rules/md/heading-increment.md

@@ -0,0 +1,46 @@
+---
+id: md/heading-increment
+title: "Heading levels go down one at a time"
+languages: [markdown]
+fix: suggest
+fix_reason: "the fix raises the skipped heading and its subsections, which changes the outline readers and tools see"
+stability: preview
+ported_from: [markdownlint/MD001]
+since: 0.1.0
+---
+
+A heading is at most one level deeper than the heading before it: `#` can be followed by `##`, not by `###`. When the front matter has a `title:`, it counts as the level-1 heading.
+
+**Why:** Headings are the document's outline; a skipped level leaves a section with no parent, which confuses screen readers and tables of contents.
+
+```codelaw
+native: md/heading-increment
+```
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+# Install
+
+### From npm
+
+Run the installer.
+````
+
+#### Do
+
+````md
+# Install
+
+## From npm
+
+Run the installer.
+````
+
+## Differences from the source
+
+The fix renumbers the whole outline at once: a raised heading's subsections move up with it.

codelaw_rules_data/rules/md/link-fragments.cases.md

@@ -0,0 +1,57 @@
+# md/link-fragments — edge cases
+
+### case: repeated headings, HTML anchor, line anchor
+
+````md
+# Notes
+
+## Usage: `x`
+
+## Usage: `x`
+
+<a id="custom"></a>
+
+[a](#usage-x-1) [b](#custom) [c](#L10) [d](#top)
+````
+
+```expect
+(none)
+```
+
+### case: wrong case
+
+````md
+# My Title
+
+[a](#My-Title)
+````
+
+```expect
+3:1 md/link-fragments
+```
+
+### case: reference definition
+
+````md
+# Title
+
+[a][x]
+
+[x]: #nowhere
+````
+
+```expect
+5:1 md/link-fragments
+```
+
+### case: percent before a multi-byte character
+
+````md
+# Title
+
+[a](#%aé) [b](#%74itle)
+````
+
+```expect
+3:1 md/link-fragments
+```

codelaw_rules_data/rules/md/link-fragments.md

@@ -0,0 +1,49 @@
+---
+id: md/link-fragments
+title: "In-page links point at a heading or anchor that exists"
+languages: [markdown]
+fix: manual
+fix_reason: "which section the link meant needs the author"
+stability: preview
+options:
+  ignore_case: { type: "boolean", default: false, description: "compare fragments with anchors ignoring case" }
+ported_from: [markdownlint/MD051]
+since: 0.1.0
+---
+
+A link to `#fragment` in the same document matches an anchor: a heading's GitHub-style id (lower case, punctuation dropped, spaces as dashes, `-1`, `-2` … for repeats), a `{#id}` after a heading, or an HTML `id` or `name`. `#top` and GitHub line anchors such as `#L20` are always valid.
+
+**Why:** A fragment that matches nothing scrolls nowhere; it is usually a heading that was renamed after the link was written.
+
+```codelaw
+native: md/link-fragments
+```
+
+## How to fix
+
+1. Find the section the link meant.
+2. Change the fragment to that heading's id, or add an anchor where the link should land.
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+# Guide
+
+## Getting started
+
+See [the first steps](#getting-startd).
+````
+
+#### Do
+
+````md
+# Guide
+
+## Getting started
+
+See [the first steps](#getting-started).
+````

codelaw_rules_data/rules/md/link-image-reference-definitions.cases.md

@@ -0,0 +1,51 @@
+# md/link-image-reference-definitions — edge cases
+
+### case: comment idiom and shortcut use
+
+````md
+[//]: # (a comment)
+
+See [docs].
+
+[docs]: https://example.com
+````
+
+```expect
+(none)
+```
+
+### case: unused definition of a fragment
+
+````md
+Text.
+
+[end]: #end
+````
+
+```expect
+3:1 md/link-image-reference-definitions
+```
+
+````fixed
+Text.
+
+````
+
+### case: defined twice
+
+````md
+See [a].
+
+[a]: https://one.example
+[a]: https://two.example
+````
+
+```expect
+4:1 md/link-image-reference-definitions
+```
+
+````fixed
+See [a].
+
+[a]: https://one.example
+````