Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
53 changes: 22 additions & 31 deletions templates/core/embedded-checks.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,57 +3,48 @@
[ID: base-embedded-checks]
[DEPENDS ON: templates/core/quality-gates.md]

For a project whose own documents carry runnable checks: context files,
runbooks, rule templates. A reader copies such a check out of the Markdown
and runs it, so it has to survive the copy.
For documents that carry checks a reader copies out and runs: context
files, runbooks, rule templates.

## Extraction

[ID: embedded-checks-extraction]

- Never indent a fenced check deeper than the first indentation of its
code; put it flush and point to it from the step
- Prefer a quoted heredoc to an inline `-c` string, and never write the
heredoc opener itself in prose
- Confirm that a line continuation survived into the committed file
- Never indent a fenced check deeper than its code's first indentation; put
it flush and point to it from the step
- Prefer a quoted heredoc to an inline `-c` string
- Never write a heredoc opener in prose
- Confirm a line continuation survived into the committed file
- Fold a command onto one line, or bind its parts to shell variables,
rather than continue it (SHOULD)
- Extract a check from the committed file and run it before merging the
rule that states it
- Report how many checks a tool could not see, not only how many it ran
- Extract a check from the committed file and run it before merging its rule

Find a check stated outside a fence. It matches over the paragraph, not
the line, because prose wraps:
## Checks

- Find every check stated outside a fence; the hook matches whole
paragraphs, since prose wraps:

```bash
pre-commit run find-unfenced-checks --all-files --verbose
```

Pass condition: the paragraph count is above zero and the
`checks stated outside a fence` count is zero. Give the hook a `--root`
argument for each directory holding rule documents; a paragraph count of
zero means the roots named nothing, not that the tree is clean.

Every embedded check MUST compile when extracted the way a reader extracts
it:
- Require paragraphs above zero and `checks stated outside a fence` zero
- Pass a `--root` for each directory of rule documents; zero paragraphs
means the roots named nothing
- Compile every embedded check as a reader extracts it (MUST):

```bash
pre-commit run compile-embedded-checks --all-files --verbose
```

Pass condition: the files-scanned and checks-found counts are above zero
and `checks that do not compile` is zero; each line after the counts names
a check that does not compile. `not applicable` means no Markdown file
holds a heredoc check.

List the lines where a continuation could be lost. The hook cannot detect
one already lost, so read its list against the source:
- Require files and checks above zero and `checks that do not compile`
zero; each later line names a failing check
- Read `not applicable` as no heredoc check in any Markdown file
- List each line where a continuation could be lost, and read it against
the source; the hook cannot see one already lost:

```bash
pre-commit run find-line-continuations --all-files --verbose
```

Pass condition: it reports the files scanned, the fenced blocks, those in a
check language and the lines among them ending in a continuation, then
lists those lines. A non-zero continuation count is a list to read, not a
failure.
- Read a non-zero continuation count as a list to review, not a failure
2 changes: 1 addition & 1 deletion tests/baselines/template-quality.txt
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ templates/backend/webhooks.md 86.9
templates/core/agents.md 100.0
templates/core/config.md 99.3
templates/core/docs.md 99.1
templates/core/embedded-checks.md 83.6
templates/core/embedded-checks.md 100.0
templates/core/git.md 89.4
templates/core/measurement.md 95.2
templates/core/oop.md 96.0
Expand Down
Loading