Skip to content
Open
Show file tree
Hide file tree
Changes from 4 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
1 change: 1 addition & 0 deletions .agents/rules/rule_authoring_standards.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,7 @@ Destinations by language, all reachable through `.githooks/pre-commit` and its `
| Python | [`pyproject.toml`](../../pyproject.toml) ruff `select` and banned-api config, mypy |
| Go | [`.golangci.yml`](../../.golangci.yml), `nogo_config.json`, custom checks in `tools/lint/` |
| TypeScript / UI | `cmd/ui/eslint.config.js`, prettier, `tools/lint/check_file_naming.py` (UI template/test and `.github/scripts/` test naming) |
| Non-UI JavaScript | [`tools/lint/eslint.nonui.config.mjs`](../../tools/lint/eslint.nonui.config.mjs) (`.github/scripts/`, `tools/nightly_tests/`, `cmd/experiment_state_server/static/`) |
| Bazel | buildifier |
| Terraform | [`.tflint.hcl`](../../.tflint.hcl) |
| Agent docs (`.agents/**/*.md`, `AGENTS.md`) | `tools/lint/check_agent_doc_paths.py` (path references must exist) |
Expand Down
31 changes: 18 additions & 13 deletions .github/scripts/git-range-diff.js
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,9 @@ function computeBulkCommitPatchIds(shas, opts) {
patchIdMap.set(sha, patchId);
}
}
} catch (_) {}
} catch (_) {
/* Best-effort cache population; caller tolerates partial map. */
}
return patchIdMap;
}

Expand Down Expand Up @@ -310,7 +312,9 @@ function resolveParentBaseFromMatch(matchedSha, commitIndex, opts) {
for (const target of [`${matchedSha}~${baseOffset}`, `${matchedSha}~1`]) {
try {
return execGit(['rev-parse', '--verify', target], { ...opts, ignoreExitCode: false }).trim();
} catch (_) {}
} catch (_) {
/* Probe next parent candidate when this offset does not exist. */
}
}
return null;
}
Expand Down Expand Up @@ -369,7 +373,9 @@ function resolveStackedApprovedRange(currentRange, approvedRange, approvedSha, p
const correlatedBase = correlateStackedParentBase(currCommits, approvedMaps, opts);
if (correlatedBase) return `${correlatedBase}..${approvedSha}`;
}
} catch (_) {}
} catch (_) {
/* Fall back to commit-count range resolution below. */
}

try {
execGit(['rev-parse', '--verify', `${approvedSha}~${prCommitCount}`], { ...opts, ignoreExitCode: false });
Expand Down Expand Up @@ -538,24 +544,23 @@ function getPrChangedFiles(baseRefOrApprovedSha, approvedShaOrCurrentSha, curren
}

if (baseRef) {
const prDiffOutput = execGit(['diff', '--name-only', `origin/${baseRef}...${headSha}`], opts);
const diffOpts = { ...opts, ignoreExitCode: false };
const prDiffOutput = execGit(['diff', '--name-only', `origin/${baseRef}...${headSha}`], diffOpts);
Comment thread
VLukiantsev marked this conversation as resolved.
Resolved
const files = new Set(prDiffOutput.split(/\r?\n/).map(f => f.trim()).filter(Boolean));

if (approvedSha && approvedSha !== headSha) {
try {
const isAncestor = execGit(['merge-base', '--is-ancestor', approvedSha, headSha], { ...opts, ignoreExitCode: true });
if (isAncestor.status === 0) {
const followUpDiff = execGit(['diff', '--name-only', approvedSha, headSha], opts);
for (const file of followUpDiff.split(/\r?\n/).map(f => f.trim()).filter(Boolean)) {
files.add(file);
}
const isAncestor = execGit(['merge-base', '--is-ancestor', approvedSha, headSha], { ...opts, ignoreExitCode: true });
if (isAncestor.status === 0) {
const followUpDiff = execGit(['diff', '--name-only', approvedSha, headSha], diffOpts);
for (const file of followUpDiff.split(/\r?\n/).map(f => f.trim()).filter(Boolean)) {
files.add(file);
}
} catch (_) {}
}
}
return Array.from(files);
}

const diffOutput = execGit(['diff', '--name-only', approvedSha, headSha], opts);
const diffOutput = execGit(['diff', '--name-only', approvedSha, headSha], { ...opts, ignoreExitCode: false });
return diffOutput.split(/\r?\n/).map(f => f.trim()).filter(Boolean);
}

Expand Down
85 changes: 77 additions & 8 deletions .github/scripts/git-range-diff.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,6 @@ const childProcess = require('child_process');
const {
Comment thread
VLukiantsev marked this conversation as resolved.
Resolved
validateGitRefs,
buildGitEnv,
execGit,
ensureGitRefs,
isFastForwardApproval,
getCommitCountInRange,
getCommitPatchId,
indexApprovedCandidateCommits,
correlateStackedParentBase,
resolveStackedApprovedRange,
resolveCommitRanges,
runGitRangeDiff,
parseNumstatDelta,
Expand Down Expand Up @@ -583,6 +575,83 @@ test('getPrChangedFiles returns files from 3-dot diff and includes follow-up com
}
});

test('getPrChangedFiles skips follow-up diff when approvedSha is unreachable or non-ancestor', () => {
const originalExec = childProcess.execFileSync;
let followUpCalled = false;
childProcess.execFileSync = (cmd, args) => {
if (cmd === 'git' && args[0] === 'diff' && args[2] === 'origin/main...headSha') {
return 'file1.go\nfile2.go\n';
}
if (cmd === 'git' && args[0] === 'merge-base' && args[1] === '--is-ancestor') {
const err = new Error('fatal: Not a valid object name approvedSha');
err.status = 128;
throw err;
}
if (cmd === 'git' && args[0] === 'diff' && args[2] === 'approvedSha' && args[3] === 'headSha') {
followUpCalled = true;
return 'file3.go\n';
}
throw new Error(`Unexpected command: ${cmd} ${args.join(' ')}`);
};

try {
const files = getPrChangedFiles('main', 'approvedSha', 'headSha');
assert.strictEqual(followUpCalled, false);
assert.deepStrictEqual(files.sort(), ['file1.go', 'file2.go']);
} finally {
childProcess.execFileSync = originalExec;
}
});

test('getPrChangedFiles propagates follow-up git diff failures instead of failing open', () => {
const originalExec = childProcess.execFileSync;
childProcess.execFileSync = (cmd, args) => {
if (cmd === 'git' && args[0] === 'diff' && args[2] === 'origin/main...headSha') {
return 'file1.go\n';
}
if (cmd === 'git' && args[0] === 'merge-base' && args[1] === '--is-ancestor') {
return '';
}
if (cmd === 'git' && args[0] === 'diff' && args[2] === 'approvedSha' && args[3] === 'headSha') {
const err = new Error('git diff failed: ETIMEDOUT');
err.status = 1;
throw err;
}
throw new Error(`Unexpected command: ${cmd} ${args.join(' ')}`);
};

try {
assert.throws(() => getPrChangedFiles('main', 'approvedSha', 'headSha'), /ETIMEDOUT/);
} finally {
childProcess.execFileSync = originalExec;
}
});

test('getPrChangedFiles normalizes ignoreExitCode to false for git diff calls', () => {
const originalExec = childProcess.execFileSync;
childProcess.execFileSync = (cmd, args) => {
if (cmd === 'git' && args[0] === 'diff' && args[2] === 'origin/main...headSha') {
return 'file1.go\n';
}
if (cmd === 'git' && args[0] === 'merge-base' && args[1] === '--is-ancestor') {
return '';
}
if (cmd === 'git' && args[0] === 'diff' && args[2] === 'approvedSha' && args[3] === 'headSha') {
return 'file2.go\n';
}
throw new Error(`Unexpected command: ${cmd} ${args.join(' ')}`);
};

try {
const threeDotFiles = getPrChangedFiles('main', 'approvedSha', 'headSha', { ignoreExitCode: true });
assert.deepStrictEqual(threeDotFiles.sort(), ['file1.go', 'file2.go']);
const twoDotFiles = getPrChangedFiles('approvedSha', 'headSha', { ignoreExitCode: true });
assert.deepStrictEqual(twoDotFiles, ['file2.go']);
} finally {
childProcess.execFileSync = originalExec;
}
});

test('getCommitModifiedFiles returns file list for commit from diff-tree', () => {
const originalExec = childProcess.execFileSync;
childProcess.execFileSync = (cmd, args) => {
Expand Down
3 changes: 2 additions & 1 deletion .github/scripts/range-diff-parser.js
Original file line number Diff line number Diff line change
Expand Up @@ -126,8 +126,9 @@ function parseRangeDiff(output) {
const addedCommitShas = [];

for (const line of lines) {
// eslint-disable-next-line no-control-regex -- intentionally strips ANSI escape codes
const cleanLine = line.replace(/\x1b\[[0-9;]*m/g, '');
const commitMatch = cleanLine.match(/^\s*(?:\d+|-):\s+([a-f0-9-]+)\s+([=!<>])\s+(?:\d+|-):\s+([a-f0-9-]+)/);
const commitMatch = cleanLine.match(/^ {0,3}(?:\d+|-):\s+([a-f0-9-]+)\s+([=!<>])\s+(?:\d+|-):\s+([a-f0-9-]+)/);
if (commitMatch) {
const status = commitMatch[2];
if (status !== '=') {
Expand Down
33 changes: 33 additions & 0 deletions .github/scripts/range-diff-parser.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -280,6 +280,39 @@ test('parseRangeDiff identifies added commits and captures addedCommitShas', ()
assert.deepStrictEqual(resultRemoved.addedCommitShas, []);
});

test('parseRangeDiff ignores commit-pair patterns in code context and commit message lines', () => {
const sampleOutput = [
'1: a1b2c3d ! 1: e5f6g7h Commit title',
' ## Commit message ##',
' 1: a1b2c3d < -: -------',
' -: ------- > 2: 89abcdef',
' @@ pkg/a.go:10,5 @@',
' 1: 0000000 = 1: 0000000',
' 1: a1b2c3d < -: -------',
' -: ------- > 2: 89abcdef',
' ++realDeltaLine()'
].join('\n');

const result = parseRangeDiff(sampleOutput);
assert.strictEqual(result.hasRemovedCommits, false);
assert.deepStrictEqual(result.addedCommitShas, []);
assert.strictEqual(result.additions, 1);
assert.strictEqual(result.totalDelta, 1);
assert.strictEqual(result.isCleanRebase, false);
});

test('parseRangeDiff matches genuine commit headers padded with up to 3 leading spaces', () => {
const sampleOutput = [
' 10: a1b2c3d = 10: e5f6g7h Tenth commit',
' -: ------- > 1000: 89abcdef Added thousandth commit'
].join('\n');

const result = parseRangeDiff(sampleOutput);
assert.strictEqual(result.hasRemovedCommits, false);
assert.deepStrictEqual(result.addedCommitShas, ['89abcdef']);
assert.strictEqual(result.isCleanRebase, false);
});

test('isIgnoredRangeDiffHeader detects metadata and header lines', () => {
assert.strictEqual(isIgnoredRangeDiffHeader('@@ Metadata'), true);
assert.strictEqual(isIgnoredRangeDiffHeader('Author: Alice <alice@google.com>'), true);
Expand Down
22 changes: 20 additions & 2 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,13 @@ jobs:
- 'tools/common/tool_utils.py'
- '.github/workflows/nightly-examples-e2e.yml'
- '.github/workflows/lint.yml'
nonui_js:
- '.github/scripts/**/*.js'
- 'tools/nightly_tests/**/*.js'
- 'cmd/experiment_state_server/static/**/*.js'
- 'tools/lint/eslint.nonui.config.mjs'
- 'cmd/ui/package-lock.json'
- '.github/workflows/lint.yml'

# 1. Python Linting (Ruff & Mypy)
- name: 'Set up Python 3.13'
Expand Down Expand Up @@ -242,15 +249,15 @@ jobs:

# 3. UI Linting & Formatting (Prettier & ESLint)
- name: 'Set up Node.js'
if: steps.changes.outputs.ui == 'true'
if: github.event_name == 'workflow_dispatch' || steps.changes.outputs.ui == 'true' || steps.changes.outputs.nonui_js == 'true'
uses: 'actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a' # v4.2.0
with:
node-version: '22'
cache: 'npm'
cache-dependency-path: 'cmd/ui/package-lock.json'

- name: 'Install UI Dependencies'
if: steps.changes.outputs.ui == 'true'
if: github.event_name == 'workflow_dispatch' || steps.changes.outputs.ui == 'true' || steps.changes.outputs.nonui_js == 'true'
run: npm ci --prefer-offline --no-audit
working-directory: 'cmd/ui'

Expand All @@ -264,6 +271,17 @@ jobs:
run: npm run lint
working-directory: 'cmd/ui'

- name: 'Run ESLint on Non-UI JS Scripts'
Comment thread
VLukiantsev marked this conversation as resolved.
Resolved
if: github.event_name == 'workflow_dispatch' || steps.changes.outputs.nonui_js == 'true'
run: |
mapfile -d '' -t NONUI_JS_FILES < <(git -c core.quotePath=false ls-files -z -- \
Comment thread
VLukiantsev marked this conversation as resolved.
Resolved
':(glob).github/scripts/**/*.js' \
':(glob)tools/nightly_tests/**/*.js' \
':(glob)cmd/experiment_state_server/static/**/*.js')
if [ "${#NONUI_JS_FILES[@]}" -gt 0 ]; then
./cmd/ui/node_modules/.bin/eslint --no-config-lookup -c tools/lint/eslint.nonui.config.mjs -- "${NONUI_JS_FILES[@]}"
fi

# 3a. GitHub Actions & Nightly JS Script Tests (node:test, no dependencies)
- name: 'Set up Node.js for JS Script Tests'
if: github.event_name == 'workflow_dispatch' || steps.changes.outputs.github_scripts == 'true' || steps.changes.outputs.examples_coverage == 'true'
Expand Down
9 changes: 5 additions & 4 deletions docs/developer.md
Original file line number Diff line number Diff line change
Expand Up @@ -255,7 +255,7 @@ Go source files (`.go`) are formatted using standard **`gofmt`**:
### 3. UI Code (`prettier` & `eslint`)
Angular and TypeScript frontend code under `cmd/ui` is formatted and linted using **Prettier** and **ESLint**:
* **`prettier`**: Enforces consistent styling on `.ts`, `.html`, and `.scss` files (`npm run format:check`).
* **`eslint`**: Enforces Angular best practices, import sorting, and TypeScript strictness (`npm run lint`).
* **`eslint`**: Enforces Angular best practices, import sorting, and TypeScript strictness under `cmd/ui` (`npm run lint`). Non-UI `.js` scripts use the separate config documented in section 8.

### 4. Bazel Build Files (`buildifier`)
Bazel build graphs (`BUILD`, `BUILD.bazel`, `WORKSPACE`, `MODULE.bazel`, and `.bzl` files) are formatted and analyzed using **`buildifier`**:
Expand All @@ -277,10 +277,11 @@ Tracked UI templates, UI test specs, and GitHub Actions script tests are checked
* Enforces `*.ng.html` for HTML files under `cmd/ui/` (requiring templates under `cmd/ui/app/` and allowing root `cmd/ui/index.html`), `*_test.ts` Karma unit test specs under `cmd/ui/app/` (rejecting `*.spec.ts`, `*_spec.ts`, and `*.test.ts` repo-wide outside `cmd/ui/screenshot_tests/`), `*.screenshot.spec.ts` Playwright specs under `cmd/ui/screenshot_tests/`, and top-level `*.test.js` Node workflow script tests under `.github/scripts/`.
* Prevents misnamed test specs (such as `foo.spec.ts` or `.github/scripts/foo_test.js`) from silently compiling without executing in Karma or CI; runs in both the pre-commit hook and CI.

### 8. GitHub Actions Workflows & Shell Scripts (`actionlint` & `shellcheck`)
Workflows and tracked shell scripts are validated in CI ([`.github/workflows/lint.yml`](../.github/workflows/lint.yml)) and locally in `.githooks/pre-commit`:
### 8. GitHub Actions Workflows, Shell Scripts & Non-UI JS (`actionlint`, `shellcheck`, `eslint`)
Workflows, tracked shell scripts, and non-UI JavaScript scripts are validated in CI ([`.github/workflows/lint.yml`](../.github/workflows/lint.yml)) and locally in `.githooks/pre-commit`:
* **`actionlint`**: Validates `.github/workflows/*.{yml,yaml}` and integrates `shellcheck` across workflow `run:` blocks.
* **`shellcheck`**: Validates tracked `*.sh` and `*.bash` scripts with `shellcheck -S style -e SC1091`.
* **Non-UI JS ESLint**: Runs `./cmd/ui/node_modules/.bin/eslint --no-config-lookup -c tools/lint/eslint.nonui.config.mjs` recursively across `.github/scripts/**/*.js`, `tools/nightly_tests/**/*.js`, and `cmd/experiment_state_server/static/**/*.js` via [`tools/lint/eslint.nonui.config.mjs`](../tools/lint/eslint.nonui.config.mjs) (reusing the ESLint installation in `cmd/ui`).
* **Node JS Script Tests**: Runs `node --test .github/scripts/*.test.js` and `node --test tools/nightly_tests/*_test.js` in CI when workflow scripts or nightly test utilities change.

---
Expand All @@ -295,7 +296,7 @@ Developers can run the pre-commit hook locally in two modes:
```
Automatically formats files and adds missing headers. Formatter fixes to files that were fully staged before the hook ran are restaged automatically ([`tools/lint/precommit_autostage.py`](../tools/lint/precommit_autostage.py)); fixes to partially staged, unstaged, or unrelated files fail the hook so you can review and stage them. Set `XMC_PRECOMMIT_NO_AUTOSTAGE=1` to disable auto-restaging. Affected Bazel unit tests are skipped when every staged path is Markdown or under `docs/`. Which checks run depends on what is staged:
* **Per-file linters and formatters** (Ruff, Prettier, ESLint, `terraform fmt`, `addlicense`) only process staged files.
* **Cross-file checks** (mypy, TFLint, `helm lint`, Trivy) also run when a staged delete or rename removes a file they cover. mypy also runs when `pyproject.toml` or a `.gitignore` changes, and TFLint when `.tflint.hcl` changes. The agent doc path check runs on any staged delete or rename.
* **Cross-file checks** (mypy, TFLint, `helm lint`, Trivy) also run when a staged delete or rename removes a file they cover. mypy also runs when `pyproject.toml` or a `.gitignore` changes, and TFLint when `.tflint.hcl` changes. The agent doc path check runs on any staged delete or rename. Staging `tools/lint/eslint.nonui.config.mjs` triggers a full non-UI JS ESLint run across tracked `.github/scripts/**/*.js`, `tools/nightly_tests/**/*.js`, and `cmd/experiment_state_server/static/**/*.js` files (in `fix` mode, a missing `cmd/ui/node_modules` warns and skips, while `--check` fails closed).
* **mypy** runs bare `mypy`, so `[tool.mypy]` in `pyproject.toml` is the single source of truth for the checked files in CI and in both hook modes. It checks every Python file in the repository, so new directories are covered automatically and edits that break unchanged importers fail locally. Two lists deny files: `.gitignore` (`exclude_gitignore`, mypy 1.16 or later) skips local-only directories such as virtualenvs, Bazel output and the `cluster-toolkit` clone, and `exclude` skips tracked files. Untracked `.py` files that `.gitignore` does not cover are checked too, so remove or fix stray scratch files before committing.

* **Check-only mode (mirrors CI validation)**:
Expand Down
1 change: 1 addition & 0 deletions tools/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@ Offline syntax walkers and static validation tooling:
- [`precommit_gates.py`](lint/precommit_gates.py): Declarative runner (`--mode fix|check`) and shared git/execution primitives for pre-commit Python lint gates (`check_legacy_imports`, `check_examples_coverage`, `check_matrix_contract`, `check_agent_doc_paths`, `check_file_naming`, `check_ui_selector_contract`).
- [`precommit_deploy_checks.py`](lint/precommit_deploy_checks.py): Pre-commit infrastructure, Helm, and Trivy security gate runner (`--mode fix|check`) covering `deploy/` and `test/helm/`.
- [`precommit_runner.py`](lint/precommit_runner.py): Top-level pure-stdlib Python orchestrator invoked by `.githooks/pre-commit` for language, UI, deploy, and affected-test gates.
- [`eslint.nonui.config.mjs`](lint/eslint.nonui.config.mjs): ESLint 10 flat configuration enforcing baseline JS correctness (`no-empty`, `no-unused-vars`, `eqeqeq`, `complexity: 15`, `max-lines-per-function: 80`) recursively across `.github/scripts/**/*.js`, `tools/nightly_tests/**/*.js`, and `cmd/experiment_state_server/static/**/*.js`; invoked by `precommit_runner.py` (`check_nonui_js`) and `.github/workflows/lint.yml`.

### 8. [`tools/migrations/components/`](migrations/components/README.md) (One-Time Component Cutover)
Temporary migration side script (`migrate.py`) for transitioning existing umbrella-managed metrics deployments to the `stable-2026a` Component profile (`prepare`, `handoff [--undo]`, `finalize`). See [`docs/migrations/components.md`](../docs/migrations/components.md).
Expand Down
Loading
Loading