Skip to content

Commit ad9abd9

Browse files
cotticotti
committed
Merge remote-tracking branch 'origin/main' into copilot/fix-build-failure-snippets
Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # src/Elastic.Markdown/Myst/Directives/Include/IncludeBlock.cs
2 parents bdd40d5 + 667e2ec commit ad9abd9

1,412 files changed

Lines changed: 96995 additions & 26998 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/settings.json‎

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,43 @@
11
{
2+
"$schema": "https://json.schemastore.org/claude-code-settings.json",
23
"permissions": {
34
"allow": [
4-
"Bash(find:*)",
5-
"Bash(wc:*)",
5+
"Read",
6+
"Glob",
7+
"Grep",
8+
"WebSearch",
9+
"WebFetch",
10+
"Bash(git log:*)",
11+
"Bash(git status:*)",
12+
"Bash(git diff:*)",
13+
"Bash(git show:*)",
14+
"Bash(git branch --list:*)",
15+
"Bash(git grep:*)",
16+
"Bash(./build.sh:*)",
617
"Bash(dotnet build:*)",
18+
"Bash(dotnet restore:*)",
19+
"Bash(dotnet test:*)",
20+
"Bash(dotnet run:*)",
21+
"Bash(dotnet format:*)",
22+
"Bash(dotnet watch:*)",
23+
"Bash(dotnet workload:*)",
24+
"Bash(npm ci:*)",
725
"Bash(npm run compile:check:*)",
8-
"Bash(npx tsc:*)",
26+
"Bash(npm run lint:*)",
27+
"Bash(npm run fmt::*)",
28+
"Bash(npm run test:*)",
29+
"Bash(npm run watch:*)",
30+
"Bash(npm run build:*)",
931
"Bash(npm exec:*)",
1032
"Bash(npm install:*)",
11-
"Bash(npm run build:*)",
12-
"Bash(git grep:*)"
33+
"Bash(npx tsc:*)",
34+
"Bash(git add:*)",
35+
"Bash(git commit:*)",
36+
"Bash(git push:*)",
37+
"Bash(gh pr create:*)",
38+
"Bash(gh pr list:*)",
39+
"Bash(gh pr view:*)",
40+
"Bash(gh label list:*)"
1341
]
1442
}
1543
}

‎.claude/skills/commit/SKILL.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
name: commit
3+
description: Stage relevant files and create a well-formed git commit for the docs-builder repo. Use this when the user asks to commit changes, save work, or create a commit.
4+
---
5+
6+
# Commit Skill
7+
8+
Creates a clean, well-formed commit following the docs-builder project conventions.
9+
10+
## Steps
11+
12+
### 1. Understand what changed
13+
14+
Run these in parallel:
15+
```bash
16+
git status
17+
git diff
18+
git diff --staged
19+
git log --oneline -5
20+
```
21+
22+
### 2. Stage files
23+
24+
Stage specific files by name — never `git add -A` or `git add .` blindly. Exclude:
25+
- `.env` files or anything with secrets/credentials
26+
- Large binaries not already tracked
27+
- Unrelated changes to the task at hand
28+
29+
### 3. Write the commit message
30+
31+
Rules:
32+
- **First line**: Imperative mood, ≤72 chars, no trailing period (e.g. `Add async timeout handling to assembler`)
33+
- **Body** (optional): One short paragraph explaining *why*, not what. Skip if the title is self-explanatory.
34+
- **Trailer**: Always append `Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>`
35+
36+
Always pass the message via HEREDOC to avoid shell escaping issues:
37+
```bash
38+
git commit -m "$(cat <<'EOF'
39+
Title here
40+
41+
Optional body explaining why.
42+
43+
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
44+
EOF
45+
)"
46+
```
47+
48+
### 4. Handle hook failures
49+
50+
This project uses **Husky.Net** git hooks:
51+
- **pre-commit**: runs prettier, eslint, typescript-check
52+
- **pre-push**: runs dotnet-lint
53+
54+
If a hook fails:
55+
1. Read the error output carefully
56+
2. Fix the underlying issue (run `/lint` if it's a formatting problem)
57+
3. Re-stage the affected files
58+
4. Create a **new commit** — never `git commit --amend` for a failed commit, and never use `--no-verify`
59+
60+
### 5. Verify success
61+
62+
Run `git status` after the commit to confirm a clean working tree.

‎.claude/skills/lint/SKILL.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
name: lint
3+
description: Auto-fix all formatting issues in the docs-builder repo — runs dotnet format for C# and npm fmt:write for TypeScript/JS. Use when the user asks to fix formatting, lint the code, or when a pre-commit hook fails due to formatting.
4+
---
5+
6+
# Lint Skill
7+
8+
Fixes all formatting issues across C# and TypeScript in the docs-builder repo.
9+
10+
## Steps
11+
12+
### 1. Fix C# formatting
13+
14+
```bash
15+
dotnet format
16+
```
17+
18+
This applies the project's editorconfig and code style rules to all C# files.
19+
20+
### 2. Fix TypeScript/JS formatting
21+
22+
```bash
23+
cd src/Elastic.Documentation.Site && npm run fmt:write
24+
```
25+
26+
This runs Prettier on all frontend source files.
27+
28+
### 3. Report results
29+
30+
After both commands complete:
31+
- If files were changed: list which files were reformatted
32+
- If nothing changed: confirm "No formatting issues found"
33+
34+
## Notes
35+
36+
- This skill fixes files in place but does **not** commit
37+
- Run this before `/commit` if you see formatting errors in build output or pre-commit hook failures
38+
- Formatting rules are enforced by Husky.Net pre-commit hooks (prettier + eslint for TS, dotnet-lint on pre-push for C#)
39+
- `dotnet format` is also available as `./build.sh lint` for the full lint pipeline

‎.claude/skills/pr/SKILL.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
name: pr
3+
description: Create a GitHub pull request for the current branch with a focused why/what body and exactly one release-drafter label. Use when the user asks to open a PR, create a pull request, or ship a branch.
4+
---
5+
6+
# PR Skill
7+
8+
Creates a GitHub PR with a body focused on *why* and *what*, labeled for the release changelog.
9+
10+
## Steps
11+
12+
### 1. Understand the branch
13+
14+
Run these to see what the PR contains:
15+
```bash
16+
git log main..HEAD --oneline
17+
git diff main...HEAD --stat
18+
```
19+
20+
### 2. Push the branch (if needed)
21+
22+
```bash
23+
git push -u origin HEAD
24+
```
25+
26+
### 3. Write the PR title
27+
28+
- ≤70 characters
29+
- Imperative mood, no trailing period
30+
- Describes the change at a human level (not a file list)
31+
32+
### 4. Write the PR body
33+
34+
Use this structure:
35+
36+
```
37+
## Why
38+
39+
<One or two sentences: the problem, gap, or need this addresses. What would go wrong without this change?>
40+
41+
## What
42+
43+
<What changed, at a meaningful level — not a file list. Think: what does a reviewer need to understand to evaluate this?>
44+
45+
## How (optional)
46+
47+
<Only include this section if a completely new architectural mechanism was introduced that future contributors need to understand at a big-picture level. Skip for normal feature additions, fixes, or refactors — those belong in code comments, not here.>
48+
```
49+
50+
**Do not** include bullet lists of changed files. Do not summarize what's already obvious from the diff.
51+
52+
### 5. Choose exactly ONE label
53+
54+
Pick the single best-fit label. Apply it with `--label <label>`.
55+
56+
| Label | Use when |
57+
|-------|----------|
58+
| `breaking` | Existing behavior or public API breaks |
59+
| `feature` | New capability that did not exist before |
60+
| `enhancement` | Improves or extends an existing feature |
61+
| `bug` | Fixes a defect in existing behavior |
62+
| `fix` | Alias for bug fix (use `bug` by preference) |
63+
| `documentation` | Docs-only change (markdown, /docs/ pages) |
64+
| `chore` | Cleanup, refactor, internal restructure — no user-visible change |
65+
| `dependencies` | Dependency version bumps |
66+
| `automation` | CI/CD, GitHub Actions, scripts, build tooling |
67+
| `ci` | Alias for automation (use `automation` by preference) |
68+
| `redesign` | Frontend visual/structural redesign work |
69+
| `changelog:skip` | Housekeeping with no changelog entry (e.g. typo fixes, config tweaks) |
70+
71+
When in doubt between `feature` and `enhancement`: `feature` = didn't exist, `enhancement` = existed but got better.
72+
73+
### 6. Create the PR
74+
75+
```bash
76+
gh pr create --title "<title>" --label "<label>" --body "$(cat <<'EOF'
77+
## Why
78+
79+
...
80+
81+
## What
82+
83+
...
84+
EOF
85+
)"
86+
```
87+
88+
### 7. Return the PR URL
89+
90+
Always print the PR URL so the user can open it directly.

‎.claude/skills/style-review/SKILL.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
name: style-review
3+
description: Review changed or staged C# code against the docs-builder coding standards and flag violations. Use when the user asks to review code style, check for standards violations, or audit a diff before committing.
4+
---
5+
6+
# Style Review Skill
7+
8+
Reviews C# changes for violations that `dotnet format` and `.editorconfig` cannot catch — behavioral patterns, naming conventions, and architectural rules.
9+
10+
## What this skill does NOT check
11+
12+
`.editorconfig` + `dotnet format` already enforce (mechanically):
13+
- `var` everywhere, no explicit types
14+
- No `this.` qualifier
15+
- Language keywords (`string` not `String`)
16+
- Expression bodies
17+
- Allman braces, newlines before `{`
18+
- Null propagation (`?.`, `??`)
19+
- Pattern matching over `is`/`as` casts
20+
- Inlined variable declarations (`out var x`)
21+
- Throw expressions, conditional delegate calls
22+
- Modifier order
23+
- File-scoped namespaces
24+
- Object/collection initializers
25+
- `[]` instead of `new List<T>()` / `Array.Empty<T>()`
26+
27+
Run `dotnet format` (or `/lint`) to fix those. Only continue with this skill for the behavioral checks below.
28+
29+
## Steps
30+
31+
### 1. Get the diff
32+
33+
```bash
34+
git diff # unstaged changes
35+
git diff --staged # staged changes
36+
git diff main...HEAD # full branch
37+
```
38+
39+
### 2. Check behavioral rules
40+
41+
**Async correctness** (error-level):
42+
- Public async methods must end in `Async`; private async methods must NOT
43+
- Never `.Result` or `.Wait()` on an async call
44+
- Library code must use `.ConfigureAwait(false)` on awaits
45+
- All async methods should accept `CancellationToken ct = default`
46+
47+
**Method design** (error-level):
48+
- Max 4 parameters — flag anything over that without a record/options object
49+
- Boolean parameters must use named argument syntax at every call site
50+
- Cyclomatic complexity > 7 branches in one method — flag and suggest extraction
51+
52+
**Structural** (error-level):
53+
- No `#region` directives
54+
- Class member order violated: fields → constructors → properties → methods (grouped by function, not visibility)
55+
56+
**Return values** (error-level):
57+
- Methods returning collections must never return `null` — must return `[]`
58+
- Lookups should use the TryGet pattern, not null returns
59+
60+
**Testing** (style-level, in `tests/` and `tests-integration/`):
61+
- New test projects should use TUnit + AwesomeAssertions, not xUnit directly
62+
- Test method naming: `MethodName_Scenario_Expected`
63+
- No assertions without fluent style (`Should().Be(...)` not `Assert.Equal(...)`)
64+
65+
**Comments** (style-level):
66+
- Comments that describe *what* the code does (not *why*) — flag for removal
67+
- Multi-paragraph docstrings on non-public members
68+
- `#region` (already error-level above)
69+
70+
### 3. Report
71+
72+
Format violations as a numbered list with severity:
73+
74+
```
75+
ERROR:
76+
1. src/Elastic.Markdown/Foo.cs:42 — public async method `GetData` missing `Async` suffix
77+
2. src/Elastic.Markdown/Foo.cs:67 — `.Result` blocks on async call; use `await`
78+
79+
STYLE:
80+
3. tests/Elastic.Markdown.Tests/Bar.cs:15 — test name `TestGetUser` should follow `GetUser_ValidId_ReturnsUser` pattern
81+
```
82+
83+
If no violations: "No behavioral style violations found."
84+
85+
### 4. Do NOT auto-fix
86+
87+
Report only. For formatting issues, run `/lint`. For logic violations (blocking async, null collections), the developer must fix manually.

‎.claude/skills/test/SKILL.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
name: test
3+
description: Run the relevant tests for what changed — detects whether to run C# unit tests, specific test projects, integration tests, or JS/TS tests based on changed files. Use when the user asks to run tests, verify changes, or check if something is broken.
4+
---
5+
6+
# Test Skill
7+
8+
Runs the right tests for what changed — fast feedback without running everything.
9+
10+
## Steps
11+
12+
### 1. Detect changed files
13+
14+
```bash
15+
git diff --name-only HEAD
16+
```
17+
18+
Or, if checking staged changes:
19+
```bash
20+
git diff --name-only --staged
21+
```
22+
23+
### 2. Pick the right test command
24+
25+
Use this decision table based on which directories have changed files:
26+
27+
| Changed path | Test command |
28+
|---|---|
29+
| `src/Elastic.Documentation.Site/` | `cd src/Elastic.Documentation.Site && npm run test` |
30+
| `src/Elastic.Markdown/` | `dotnet test tests/Elastic.Markdown.Tests/` |
31+
| `src/Elastic.Documentation.Configuration/` | `dotnet test tests/Elastic.Documentation.Configuration.Tests/` |
32+
| `src/Elastic.Documentation.Navigation/` or `Navigation.Tests/` | `dotnet test tests/Navigation.Tests/` |
33+
| `src/Elastic.ApiExplorer/` | `dotnet test tests/Elastic.ApiExplorer.Tests/` |
34+
| `tests-integration/` | `./build.sh integrate` |
35+
| `src/tooling/docs-builder/` | `./build.sh unit-test` |
36+
| Multiple areas or uncertain | `./build.sh unit-test` |
37+
38+
If files span more than two source areas, prefer `./build.sh unit-test` to run all unit tests at once.
39+
40+
### 3. Run and report
41+
42+
- Show the command being run
43+
- On **pass**: summarize pass count, confirm all green
44+
- On **fail**: show the specific failing test(s), the error message, and suggest a fix approach based on the failure
45+
46+
## Notes
47+
48+
- Integration tests (`./build.sh integrate`) require cloned repos and take significantly longer — only run when integration test files changed or the user explicitly asks
49+
- When in doubt, `./build.sh unit-test` is the safe default (completes in under a minute)
50+
- TypeScript type checking (not tests) is `npm run compile:check` from `src/Elastic.Documentation.Site/`

0 commit comments

Comments
 (0)