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

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

@@ -0,0 +1,40 @@
+---
+id: md/link-image-reference-definitions
+title: "Every reference definition is used, and defined once"
+languages: [markdown]
+fix: auto
+stability: preview
+options:
+  ignored_definitions: { type: "string[]", default: ["//"], description: "labels never reported (`[//]: # (…)` is a comment idiom)" }
+ported_from: [markdownlint/MD053]
+since: 0.1.0
+---
+
+A `[label]: url` definition is referred to by some link or image, and no label is defined twice. The fix deletes the unused or repeated definition.
+
+**Why:** A definition nothing uses is dead text that goes stale, and only the first of two definitions counts, so the second one misleads.
+
+```codelaw
+native: md/link-image-reference-definitions
+```
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+Read [the spec][spec].
+
+[spec]: https://spec.commonmark.org/
+[old]: https://example.com/old
+````
+
+#### Do
+
+````md
+Read [the spec][spec].
+
+[spec]: https://spec.commonmark.org/
+````

codelaw_rules_data/rules/md/no-alt-text.md

@@ -0,0 +1,47 @@
+---
+id: md/no-alt-text
+title: "Images have alt text"
+languages: [markdown]
+fix: manual
+fix_reason: "describing the image needs a person who can see it"
+stability: preview
+ported_from: [markdownlint/MD045]
+since: 0.1.0
+---
+
+A Markdown image has alt text: `![what it shows](…)`. HTML `<img>` elements are checked by `html/img-alt` in the HTML pack.
+
+**Why:** Screen readers read the alt text in place of the image, and it shows when the image fails to load.
+
+```codelaw
+match:
+  kind: image
+  not:
+    has: { kind: image_description }
+message: "Describe the image in its alt text: `![what it shows](…)`"
+```
+
+## How to fix
+
+1. Look at the image and say in a few words what it shows.
+2. Put that between the brackets; for a purely decorative image, use HTML with `alt=""`.
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+![](diagram.png)
+````
+
+#### Do
+
+````md
+![The request flow from client to cache](diagram.png)
+````
+
+## Differences from the source
+
+markdownlint also checks HTML `<img>`; here that is the HTML pack's `html/img-alt`, which lints HTML embedded in Markdown.

codelaw_rules_data/rules/md/no-bare-urls.cases.md

@@ -0,0 +1,37 @@
+# md/no-bare-urls — edge cases
+
+### case: already linked or in code
+
+````md
+See <https://a.example>, [b](https://b.example), `https://c.example` and <a href="https://d.example">d</a>.
+````
+
+```expect
+(none)
+```
+
+### case: closing parenthesis
+
+````md
+Docs (https://example.com/a_(b)).
+````
+
+```expect
+1:7 md/no-bare-urls
+```
+
+````fixed
+Docs (<https://example.com/a_(b)>).
+````
+
+### case: other schemes and rejected links
+
+````md
+Repository: git+https://github.com/a/b.git
+
+By [Ann Lee](https://github.com/Ann Lee).
+````
+
+```expect
+(none)
+```

codelaw_rules_data/rules/md/no-bare-urls.md

@@ -0,0 +1,37 @@
+---
+id: md/no-bare-urls
+title: "URLs are links, not bare text"
+languages: [markdown]
+fix: auto
+stability: preview
+ported_from: [markdownlint/MD034]
+since: 0.1.0
+---
+
+A URL in running text is wrapped in angle brackets, `<https://…>`, or written as a link. URLs in code spans, links, autolinks and HTML are left alone.
+
+**Why:** CommonMark only links a URL in angle brackets; a bare one is plain text in many renderers.
+
+```codelaw
+native: md/no-bare-urls
+```
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+The docs are at https://example.com/docs.
+````
+
+#### Do
+
+````md
+The docs are at <https://example.com/docs>.
+````
+
+## Differences from the source
+
+Bare e-mail addresses are not reported.

codelaw_rules_data/rules/md/no-duplicate-heading.cases.md

@@ -0,0 +1,19 @@
+# md/no-duplicate-heading — edge cases
+
+### case: changelog sections
+
+````md
+# Changelog
+
+## 1.1.0
+
+### Fixed
+
+## 1.0.0
+
+### Fixed
+````
+
+```expect
+(none)
+```

codelaw_rules_data/rules/md/no-duplicate-heading.md

@@ -0,0 +1,61 @@
+---
+id: md/no-duplicate-heading
+title: "No two sibling headings with the same text"
+languages: [markdown]
+fix: manual
+fix_reason: "which heading to rename, and to what, needs the author"
+stability: preview
+options:
+  siblings_only: { type: "boolean", default: true, description: "only compare headings under the same parent; `false` compares every heading in the document" }
+ported_from: [markdownlint/MD024]
+since: 0.1.0
+---
+
+Headings under the same parent heading have different text.
+
+**Why:** Readers and tables of contents tell sections apart by their headings, and repeated headings get anchors (`#setup`, `#setup-1`) that are easy to link to the wrong one.
+
+```codelaw
+native: md/no-duplicate-heading
+```
+
+## How to fix
+
+1. Decide whether the two sections are one topic; if so, merge them.
+2. Otherwise rename one heading to say how it differs.
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+# Tools
+
+## Setup
+
+Install the CLI.
+
+## Setup
+
+Configure it.
+````
+
+#### Do
+
+````md
+# Tools
+
+## Setup
+
+Install the CLI.
+
+## Configuration
+
+Configure it.
+````
+
+## Differences from the source
+
+`siblings_only` defaults to `true` here (markdownlint defaults it to `false`), so a changelog's repeated `### Fixed` under each version is not reported.

codelaw_rules_data/rules/md/no-emphasis-as-heading.cases.md

@@ -0,0 +1,23 @@
+# md/no-emphasis-as-heading — edge cases
+
+### case: emphasis inside a sentence
+
+````md
+Use **only** this.
+
+*Note: it is slow.*
+````
+
+```expect
+(none)
+```
+
+### case: emphasis around a link
+
+````md
+*For version 1, see [the old docs](v1.md)*
+````
+
+```expect
+(none)
+```

codelaw_rules_data/rules/md/no-emphasis-as-heading.md

@@ -0,0 +1,49 @@
+---
+id: md/no-emphasis-as-heading
+title: "Headings are headings, not bold lines"
+languages: [markdown]
+fix: manual
+fix_reason: "which heading level the line should become depends on the outline"
+stability: preview
+options:
+  punctuation: { type: "string", default: ".,;:!?。，；：！？", description: "a line ending in one of these is a sentence, not a heading" }
+ported_from: [markdownlint/MD036]
+since: 0.1.0
+---
+
+A paragraph that is a single line of bold or italic text, standing alone, is a heading. Lines ending in punctuation are sentences and are not reported.
+
+**Why:** Emphasis only looks like a heading: it doesn't appear in the outline, gets no anchor and isn't announced as a heading by screen readers.
+
+```codelaw
+native: md/no-emphasis-as-heading
+```
+
+## How to fix
+
+1. Pick the level the section belongs at.
+2. Replace the emphasis with a heading of that level.
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+# Guide
+
+**Installation**
+
+Run the installer.
+````
+
+#### Do
+
+````md
+# Guide
+
+## Installation
+
+Run the installer.
+````

codelaw_rules_data/rules/md/no-empty-links.md

@@ -0,0 +1,50 @@
+---
+id: md/no-empty-links
+title: "Links have a destination"
+languages: [markdown]
+fix: manual
+fix_reason: "where the link should go needs the author"
+stability: preview
+ported_from: [markdownlint/MD042]
+since: 0.1.0
+---
+
+A link has a destination: not `()`, `(<>)` or a bare `(#)`.
+
+**Why:** An empty link looks clickable but goes nowhere, usually because a URL was never filled in.
+
+```codelaw
+match:
+  kind: inline_link
+  any:
+    - not: { has: { kind: link_destination } }
+    - has: { kind: link_destination, regex: '^(#|<>|<#>)$' }
+message: "This link goes nowhere; give it a destination"
+```
+
+## How to fix
+
+1. Find where the link should point.
+2. Write that destination, or remove the link and keep its text.
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+See [the changelog]().
+````
+
+#### Don't
+
+````md
+See [the changelog](#).
+````
+
+#### Do
+
+````md
+See [the changelog](CHANGELOG.md).
+````

codelaw_rules_data/rules/md/no-inline-html.cases.md

@@ -0,0 +1,13 @@
+# md/no-inline-html — edge cases
+
+### case: comments and allowed closing tags
+
+````md
+<!-- generated -->
+
+Text.
+````
+
+```expect
+(none)
+```

codelaw_rules_data/rules/md/no-inline-html.md

@@ -0,0 +1,45 @@
+---
+id: md/no-inline-html
+title: "No raw HTML in Markdown"
+languages: [markdown]
+fix: manual
+fix_reason: "the Markdown equivalent, if there is one, needs the author"
+stability: preview
+options:
+  allowed_elements: { type: "string[]", default: [], description: "element names that may be used, such as `details` or `kbd`" }
+ported_from: [markdownlint/MD033]
+since: 0.1.0
+---
+
+A Markdown document doesn't use raw HTML elements, except those listed in `allowed_elements`. HTML comments are not reported.
+
+**Why:** Raw HTML ties the document to renderers that pass it through; many (GitHub among them) strip some of it, and it hides the structure Markdown tools read.
+
+```codelaw
+native: md/no-inline-html
+```
+
+## How to fix
+
+1. Rewrite the element in Markdown where an equivalent exists.
+2. Where none does, add the element to `allowed_elements`.
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+<b>Note:</b> back up first.
+````
+
+#### Do
+
+````md
+**Note:** back up first.
+````
+
+## Notes
+
+This rule is in `data/conventions`, not `md/recommended`: most READMEs rely on HTML for layout (centred logos, `<details>`), so it is a house style rather than a correctness check.

codelaw_rules_data/rules/md/no-reversed-links.md

@@ -0,0 +1,33 @@
+---
+id: md/no-reversed-links
+title: "Links are written [text](url), not (text)[url]"
+languages: [markdown]
+fix: auto
+stability: preview
+ported_from: [markdownlint/MD011]
+since: 0.1.0
+---
+
+Text written as `(text)[url]` is a link with its brackets swapped. Footnote references such as `(note)[^1]` are not reported.
+
+**Why:** The reversed form doesn't render as a link: readers see the brackets and the raw URL.
+
+```codelaw
+native: md/no-reversed-links
+```
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+Read (the guide)[https://example.com/guide].
+````
+
+#### Do
+
+````md
+Read [the guide](https://example.com/guide).
+````

codelaw_rules_data/rules/md/reference-links-images.cases.md

@@ -0,0 +1,40 @@
+# md/reference-links-images — edge cases
+
+### case: shortcuts and task lists
+
+````md
+- [x] done
+- [ ] todo
+
+See [CommonMark].
+````
+
+```expect
+(none)
+```
+
+### case: labels ignore case
+
+````md
+Read [the spec][Spec].
+
+[spec]: https://spec.commonmark.org/
+````
+
+```expect
+(none)
+```
+
+### case: definition of a fragment
+
+````md
+Jump to [the end][end].
+
+## End
+
+[end]: #end
+````
+
+```expect
+(none)
+```

codelaw_rules_data/rules/md/reference-links-images.md

@@ -0,0 +1,44 @@
+---
+id: md/reference-links-images
+title: "Reference links use a label that is defined"
+languages: [markdown]
+fix: manual
+fix_reason: "where the reference should point needs the author"
+stability: preview
+options:
+  ignored_labels: { type: "string[]", default: ["x"], description: "labels never reported (`x` is a task-list checkbox)" }
+  shortcut_syntax: { type: "boolean", default: false, description: "also check `[label]` shortcuts, which plain bracketed text looks like" }
+ported_from: [markdownlint/MD052]
+since: 0.1.0
+---
+
+A reference link or image — `[text][label]`, `[label][]`, `![alt][label]` — uses a label that a `[label]: url` definition in the document defines. Labels match ignoring case and spacing.
+
+**Why:** A reference to an undefined label isn't a link at all: it renders as the literal brackets.
+
+```codelaw
+native: md/reference-links-images
+```
+
+## How to fix
+
+1. Check the label for a typo against the definitions.
+2. Fix the label, or add the missing `[label]: url` definition.
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+Read [the spec][spec].
+````
+
+#### Do
+
+````md
+Read [the spec][spec].
+
+[spec]: https://spec.commonmark.org/
+````

codelaw_rules_data/rules/md/relative-links.md

@@ -0,0 +1,46 @@
+---
+id: md/relative-links
+title: "Relative links point at a file that exists"
+languages: [markdown]
+fix: manual
+fix_reason: "whether the file moved, was renamed or was never written needs the author"
+stability: preview
+since: 0.1.0
+---
+
+A link or image whose destination is a path, not a URL, names a file or folder of the project. The path is read from the linking file's folder (from the project root when it starts with `/`), without its `#fragment` or `?query`. Links with a scheme (`https:`, `mailto:`), in-page `#fragments`, template syntax and paths that leave the project are not checked.
+
+**Why:** A relative link breaks silently when the file it names is moved or renamed; the reader gets a 404 where the documentation should be.
+
+```codelaw
+native: md/relative-links
+```
+
+## How to fix
+
+1. Find where the file went: `git log --follow --stat -- <path>` shows a rename.
+2. Point the link at the file's new path, or remove the link if the file is gone.
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+<!-- docs/guide.md -->
+Start with [the setup](./setup.md), then read the [FAQ](../FAQ.md).
+<!-- docs/setup.md -->
+# Setup
+````
+
+#### Do
+
+````md
+<!-- docs/guide.md -->
+Start with [the setup](./setup.md), then read the [FAQ](../FAQ.md).
+<!-- docs/setup.md -->
+# Setup
+<!-- FAQ.md -->
+# FAQ
+````

codelaw_rules_data/rules/md/single-h1.cases.md

@@ -0,0 +1,29 @@
+# md/single-h1 — edge cases
+
+### case: front matter title
+
+````md
+---
+title: Guide
+---
+
+# Guide
+````
+
+```expect
+5:1 md/single-h1
+```
+
+### case: setext headings count
+
+````md
+Guide
+=====
+
+Usage
+=====
+````
+
+```expect
+4:1 md/single-h1
+```

codelaw_rules_data/rules/md/single-h1.md

@@ -0,0 +1,57 @@
+---
+id: md/single-h1
+title: "One level-1 heading per document"
+languages: [markdown]
+fix: manual
+fix_reason: "which heading is the title, and what level the others become, needs the author"
+stability: preview
+options:
+  level: { type: "integer", default: 1, description: "the level of the title heading" }
+ported_from: [markdownlint/MD025]
+since: 0.1.0
+---
+
+A document has one top-level heading, its title. Every later level-1 heading is reported; when the front matter has a `title:`, every level-1 heading is.
+
+**Why:** The level-1 heading names the document; a second one splits the outline in two and gives the page two titles.
+
+```codelaw
+native: md/single-h1
+```
+
+## How to fix
+
+1. Keep the heading that names the document at level 1.
+2. Make the others level 2 and shift their subsections down to match.
+
+## Examples
+
+### Markdown
+
+#### Don't
+
+````md
+# Guide
+
+Intro.
+
+# Usage
+
+Steps.
+````
+
+#### Do
+
+````md
+# Guide
+
+Intro.
+
+## Usage
+
+Steps.
+````
+
+## Differences from the source
+
+markdownlint applies the rule only when the first line of the file is the level-1 heading; here the first level-1 heading anywhere is the title, so a README that starts with badges is checked too.