Skip to content

Commit 9f0c211

Browse files
RomanNikitenkoRomanNikitenko
committed
Add 'validate-rebase-rules' skill
Signed-off-by: Roman Nikitenko <rnikiten@redhat.com> Generated-by: Cursor AI
1 parent 73bb214 commit 9f0c211

4 files changed

Lines changed: 463 additions & 4 deletions

File tree

‎.claude/skills/validate-rebase-rules/SKILL.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
name: validate-rebase-rules
3+
description: Validates that .rebase/ rules (replace, add, override) are still current against upstream VS Code. Generates a rebase-rules-validation.md report with mismatches and proposed fixes. Use when asked to check, validate, or audit rebase rules, or before a rebase.
4+
---
5+
6+
# Validate Rebase Rules
7+
8+
Check whether `.rebase/` rules are still applicable to the current upstream VS Code version and the current che-code branch. Produce a `rebase-rules-validation.md` report listing any problems found.
9+
10+
## Prerequisites
11+
12+
Ensure the `upstream-code` remote exists and is fetched:
13+
14+
```bash
15+
git remote get-url upstream-code || git remote add upstream-code https://github.com/microsoft/vscode
16+
git fetch upstream-code
17+
```
18+
19+
## Step 1 — Resolve versions from rebase.sh
20+
21+
Read `rebase.sh` and extract two variables:
22+
23+
- `CURRENT_UPSTREAM_VERSION` — e.g. `release/1.108`
24+
- `PREVIOUS_UPSTREAM_VERSION` — e.g. `release/1.104`
25+
26+
These are defined near the top of `rebase.sh` as shell variable assignments.
27+
28+
Use the upstream git ref `upstream-code/<version>` when fetching file content:
29+
30+
```bash
31+
git show upstream-code/<version>:<path>
32+
```
33+
34+
Where `<path>` is **without** the `code/` prefix (upstream stores VS Code sources at repo root).
35+
36+
## Step 2 — Validate `.rebase/replace/` rules
37+
38+
Each file under `.rebase/replace/` has the form `.rebase/replace/<code-path>.json` and contains a JSON array of `{ "from": "...", "by": "..." }` objects.
39+
40+
**Path mapping:**
41+
42+
| Context | Path |
43+
|---------|------|
44+
| Rule file | `.rebase/replace/<code-path>.json` |
45+
| Upstream file | `<code-path>` with leading `code/` stripped → use as path in `git show upstream-code/CURRENT_UPSTREAM_VERSION:<stripped-path>` |
46+
| che-code file | `<code-path>` in the current working tree |
47+
48+
**For each rule entry:**
49+
50+
1. **Check `from` in upstream.** Fetch the upstream file at `CURRENT_UPSTREAM_VERSION`. Verify the `from` string exists verbatim in that file content. Handle escape sequences in the JSON: `\n` → newline, `\t` → tab, `\\` → backslash. The actual file content must contain the **decoded** string.
51+
52+
2. **Check `by` in che-code.** Read the che-code file from the current working tree. Verify the decoded `by` string exists in it. Again, decode JSON escapes before matching.
53+
54+
3. **On mismatch — propose a fix.**
55+
- Fetch the same file at `PREVIOUS_UPSTREAM_VERSION`.
56+
- Compare the `PREVIOUS_UPSTREAM_VERSION` content with the `CURRENT_UPSTREAM_VERSION` content around the area where `from` was expected.
57+
- Identify what changed and propose the corrected `from` or `by` value.
58+
59+
**Important note on escape handling in replace rules:**
60+
The replace rules use a custom escaping convention (not standard JSON escapes). For example `\\\n` means literal newline, `\\\t` means literal tab. When reading the JSON with `jq -r`, these are automatically decoded to actual newline/tab characters. Always use `jq -r '.from'` and `jq -r '.by'` to get the real strings for comparison.
61+
62+
## Step 3 — Validate `.rebase/add/` rules
63+
64+
Files under `.rebase/add/` are JSON fragments that get **merged into** upstream files using jq: `jq -s '.[1] * .[0]' <add-file> <upstream-file>` — the add-rule values take priority for conflicting keys. By convention, add rules are intended for keys absent in upstream, so conflicts should not occur.
65+
66+
### 3a — Check upstream for conflicts
67+
68+
The purpose of `add` rules is to add keys that **do not exist** in upstream. If a key now exists in upstream, the rule may be redundant or causing a silent override.
69+
70+
**For each file in `.rebase/add/`:**
71+
72+
1. Identify the upstream file path (strip `code/` prefix).
73+
2. Read the add rule JSON.
74+
3. Fetch the upstream file at `CURRENT_UPSTREAM_VERSION`.
75+
4. For every leaf key/value in the add rule, check if that key exists in the upstream file:
76+
- **Key absent in upstream** → OK, the add rule is still needed.
77+
- **Key exists with the same value** → WARNING: add rule is redundant, upstream already has this value. Consider removing it.
78+
- **Key exists with a different value** → WARNING: the add rule silently overrides the upstream value. This is a potential conflict.
79+
- For version-like values (semver): if upstream version ≥ add-rule version → the add rule may be downgrading. Report as WARNING.
80+
- For non-version values: report the upstream value vs add-rule value for manual review.
81+
82+
### 3b — Check che-code for correct application
83+
84+
Verify that the add rule values are actually present in the current che-code working tree.
85+
86+
**For each file in `.rebase/add/`:**
87+
88+
1. Identify the corresponding che-code file (same path, e.g. `.rebase/add/code/package.json` → `code/package.json`).
89+
2. Read the che-code file from the working tree.
90+
3. Read the add rule JSON.
91+
4. For every leaf key/value in the add rule, verify it is present in the che-code file:
92+
- For flat key-value pairs, check exact key and value presence.
93+
- For nested objects (e.g. `dependencies`, `devDependencies`, `overrides`), check that each leaf key-value from the add rule appears in the corresponding section of the che-code file.
94+
5. If a value from the add rule is **not** found in the che-code file, report it as ERROR: rule was not applied or was overwritten.
95+
96+
**Note:** For `product.json` add rules, check nested arrays and objects similarly — verify each element/key is present.
97+
98+
## Step 4 — Validate `.rebase/override/` rules
99+
100+
Files under `.rebase/override/` are JSON fragments merged **over** upstream files using jq: `jq -s '.[0] * .[1]' <upstream-file> <override-file>` — override values take priority.
101+
102+
**For each file in `.rebase/override/`:**
103+
104+
1. Identify the upstream file path (strip `code/` prefix).
105+
2. Read the override rule JSON.
106+
3. Fetch the upstream file at `CURRENT_UPSTREAM_VERSION`.
107+
4. For every leaf key in the override rule:
108+
a. **Check key still exists in upstream.** If the key no longer exists in the upstream file at `CURRENT_UPSTREAM_VERSION`, report a warning: the override may be unnecessary or the upstream structure changed.
109+
b. **For version-like values (semver patterns like `^X.Y.Z`):** Compare the upstream value with the override value. Use semver logic:
110+
- If upstream version ≥ override version → report a warning (override may no longer be needed because upstream already meets or exceeds the required version).
111+
- If upstream version < override version → OK, override is still needed.
112+
c. **For non-version values:** If the upstream value already equals the override value, report a warning (override is redundant).
113+
114+
**Semver comparison guidance:**
115+
Strip leading `^`, `~`, `>=` etc. before comparing. Compare major.minor.patch numerically. For example, `^5.1.9` override vs `^5.1.0` upstream → upstream `5.1.0 < 5.1.9` → OK. But `^5.1.9` override vs `^5.2.0` upstream → upstream `5.2.0 > 5.1.9` → warn.
116+
117+
## Step 5 — Generate the report
118+
119+
Create `rebase-rules-validation.md` in the repository root. Only create this file if there are findings to report. If all rules are valid, inform the user and do not create the file.
120+
121+
### Report format
122+
123+
```markdown
124+
# Rebase Rules Validation Report
125+
126+
> Generated against upstream `<CURRENT_UPSTREAM_VERSION>` (previous: `<PREVIOUS_UPSTREAM_VERSION>`)
127+
128+
## Critical findings
129+
130+
<!-- Numbered list of the most important actionable items, e.g.: -->
131+
1. **Short description** — Why it matters and what to do.
132+
2. ...
133+
134+
---
135+
136+
## Replace Rules
137+
138+
| Rule file | Problematic value | Proposed fix |
139+
|-----------|-------------------|--------------|
140+
| `.rebase/replace/code/src/server-main.js.json` | `"from": "const product = ..."` not found in upstream | `"from": "const product = <new value>"` |
141+
142+
## Add Rules
143+
144+
| Rule file | Issue |
145+
|-----------|-------|
146+
| `.rebase/add/code/package.json` | Key `dependencies.ws` with value `8.2.3` not found in `code/package.json` |
147+
148+
## Override Rules
149+
150+
| Rule file | Key | Issue |
151+
|-----------|-----|-------|
152+
| `.rebase/override/code/extensions/npm/package.json` | `dependencies.minimatch` | Upstream already at `^5.2.0` which is ≥ override `^5.1.9` — override may be unnecessary |
153+
```
154+
155+
### Severity indicators
156+
157+
Use these prefixes in the Issue/Proposed fix column:
158+
159+
- **ERROR** — `from` or `by` value not found; rule will fail during rebase
160+
- **WARNING** — override may be unnecessary or redundant
161+
- **INFO** — value changed but rule still works
162+
163+
## Workflow summary
164+
165+
1. Fetch upstream remote.
166+
2. Extract versions from `rebase.sh`.
167+
3. Enumerate all files under `.rebase/replace/`, `.rebase/add/`, `.rebase/override/`.
168+
4. For each rule, perform the checks described above.
169+
5. Collect all findings.
170+
6. Generate `rebase-rules-validation.md` if there are findings. Otherwise report success.
171+
172+
## Parallelization guidance
173+
174+
When checking rules, launch parallel subagents or batch operations where possible:
175+
176+
- All `.rebase/replace/` rule files can be checked independently.
177+
- All `.rebase/add/` rule files can be checked independently.
178+
- All `.rebase/override/` rule files can be checked independently.
179+
- Upstream file fetches (`git show`) can be batched.
180+
181+
## Missing file handling
182+
183+
Apply these rules across all steps when a target file cannot be found:
184+
185+
| File missing | Behavior |
186+
|--------------|----------|
187+
| **Upstream file not found** (`git show` fails) | Report as ERROR: the file was likely removed or renamed in VS Code. The entire rule file is suspect and should be reviewed. |
188+
| **Che-code file not found** in working tree | Report as ERROR: the file is missing. The rule targets a file that does not exist in che-code. |
189+
190+
## Edge cases
191+
192+
- Some replace rules use multiline `from`/`by` values with `\\\n` and `\\\t` escapes. Always decode before matching.
193+
- `code/package.json` can have both replace, add, and override rules simultaneously. Check each independently.
194+
- `product.json` uses tab indentation (see `override_json_file` call with `"tab"` parameter in `rebase.sh`).

‎CLAUDE.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
**che-code** is Eclipse Che's fork of Microsoft's VS Code (Code-OSS) that runs in a browser, connecting to a remote HTTP(s) server on Kubernetes instead of desktop mode. The terminal is container-aware: it can open shells in any container of the running pod.
8+
9+
Upstream VS Code is stored as a Git subtree in the `code/` directory. The repository is self-contained (no submodule setup needed).
10+
11+
## Build & Development Commands
12+
13+
### Development Mode
14+
```bash
15+
npm install # Install deps + download built-in extensions (runs in code/)
16+
npm run watch # Compile and watch for changes
17+
npm run server # Run VS Code server at localhost:8000 (dev mode)
18+
```
19+
20+
### Production Build
21+
```bash
22+
npm run build # Build vscode-reh-web-linux-x64 (unminified)
23+
npm run build:min # Build vscode-reh-web-linux-x64 (minified)
24+
npm run rebuild-native-modules # Rebuild native Node modules
25+
```
26+
27+
### Container Image Build (in order)
28+
```bash
29+
podman build -f build/dockerfiles/linux-musl.Dockerfile -t linux-musl .
30+
podman build -f build/dockerfiles/linux-libc-ubi8.Dockerfile -t linux-libc-ubi8 .
31+
podman build -f build/dockerfiles/linux-libc-ubi9.Dockerfile -t linux-libc-ubi9 .
32+
podman build -f build/dockerfiles/assembly.Dockerfile -t che-code .
33+
```
34+
35+
### Running the Container Locally
36+
```bash
37+
podman run --rm -it -p 3100:3100 -e CODE_HOST=0.0.0.0 quay.io/che-incubator/che-code:next
38+
```
39+
40+
### Tests (inside `code/`)
41+
```bash
42+
cd code
43+
npm run test-node # Mocha unit tests (Node.js)
44+
npm run test-browser # Browser unit tests (Playwright)
45+
npm run test-extension # Extension tests (vscode-test)
46+
npm run smoketest # Full smoke test suite
47+
```
48+
49+
### Linting (inside `code/`)
50+
```bash
51+
cd code
52+
node build/eslint # ESLint
53+
node build/stylelint # Stylelint
54+
npm run hygiene # Full hygiene check (formatting, imports, layers)
55+
npm run valid-layers-check # Architecture layer validation
56+
```
57+
58+
### Launcher (`launcher/`)
59+
```bash
60+
cd launcher
61+
npm run compile # TypeScript compile
62+
npm run lint # ESLint
63+
npm run format # Prettier check
64+
npm run format:fix # Prettier auto-fix
65+
npm run build # Full build (format + compile + lint + test)
66+
```
67+
Launcher uses Jest for testing, TypeScript 5.6+, and ES2022 modules.
68+
69+
### Che Extension License Check
70+
```bash
71+
npm --prefix code/extensions/che-api run license:generate
72+
```
73+
Replace `che-api` with any Che extension name. Generates dependency reports in `.deps/`.
74+
75+
## Architecture
76+
77+
### Directory Structure
78+
79+
- **`code/`** — VS Code upstream (git subtree) with Che modifications. This is where the bulk of the editor source lives (`code/src/vs/`, `code/extensions/`).
80+
- **`launcher/`** — Standalone TypeScript project that configures and launches VS Code in Kubernetes. Handles workspace config, product.json generation, Open VSX registry integration, SSL certificates, and Kubernetes API interaction.
81+
- **`build/dockerfiles/`** — Multi-stage Dockerfiles for three platform targets (musl/Alpine, libc-ubi8, libc-ubi9) plus an assembly Dockerfile that combines them.
82+
- **`build/scripts/`** — Container entrypoint scripts (`entrypoint.sh`, `entrypoint-volume.sh`, `entrypoint-init-container.sh`).
83+
- **`build/artifacts/`** — `artifacts.lock.yaml` locks built-in extension versions with SHA256 checksums. Regenerate with `./build/artifacts/generate.sh`.
84+
- **`branding/`** — UI branding customization (icons, product.json overrides, CSS). Applied via `branding/branding.sh`.
85+
- **`.rebase/`** — Patch management for upstream rebasing:
86+
- `add/` — Files to add to upstream
87+
- `override/` — JSON files to merge over upstream (via jq)
88+
- `replace/` — Files to wholesale replace in upstream
89+
90+
### Che-Specific Extensions (in `code/extensions/`)
91+
92+
Nine extensions provide Kubernetes/Che integration:
93+
- `che-api` — API for Che platform integration
94+
- `che-activity-tracker` — User activity tracking
95+
- `che-commands` — Custom command support
96+
- `che-github-authentication` — GitHub OAuth flow
97+
- `che-port` — Port exposure management for pods
98+
- `che-remote` — Remote workspace status indicator
99+
- `che-resource-monitor` — Resource usage monitoring
100+
- `che-terminal` — Container-aware terminal (open shells in any pod container)
101+
- `che-telemetry` — Telemetry collection
102+
103+
### Key Entry Points
104+
105+
- `code/src/server-main.ts` — VS Code remote server entry point
106+
- `code/src/vs/` — Core VS Code modules (layered architecture enforced by `valid-layers-check`)
107+
- `launcher/src/entrypoint.ts` — Launcher entry point for Kubernetes environments
108+
- `launcher/src/vscode-launcher.ts` — VS Code process management
109+
110+
### Upstream Rebase Workflow
111+
112+
To rebase on upstream VS Code:
113+
1. `git remote add upstream-code https://github.com/microsoft/vscode` (if not already added)
114+
2. `git fetch upstream-code main`
115+
3. `./rebase.sh` — Pulls subtree, applies `.rebase/` patches, updates JSON overrides
116+
4. Fix any conflicts
117+
5. `./build/artifacts/generate.sh` to update `artifacts.lock.yaml`
118+
119+
### Build System
120+
121+
The `code/` directory uses Gulp as its build system. Key gulp tasks:
122+
- `vscode-reh-web-linux-x64` / `vscode-reh-web-linux-x64-min` — Build the remote web host
123+
- `watch-client` / `watch-extensions` — Watch mode (both run in parallel via `npm run watch`)
124+
- `compile-build-with-mangling` — Production compilation with name mangling
125+
126+
Node.js version must match what upstream VS Code requires (check `code/remote/.npmrc` for the `target` property).
127+
128+
### Multi-Platform Container Strategy
129+
130+
The final image is assembled from three platform-specific builds:
131+
- **linux-musl** — Alpine Linux (musl libc)
132+
- **linux-libc-ubi8** — Red Hat UBI 8
133+
- **linux-libc-ubi9** — Red Hat UBI 9
134+
135+
The `assembly.Dockerfile` combines all three into a single image that selects the right binary at runtime.

0 commit comments

Comments
 (0)