From 410fd1b936abbbc976d655699ce378c8c94d427c Mon Sep 17 00:00:00 2001 From: Denis Yuen Date: Wed, 7 Oct 2026 14:15:17 -0400 Subject: [PATCH] Add CLAUDE.md SEAB-7772 Co-Authored-By: Claude Sonnet 5.5 --- CLAUDE.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..35df70d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,97 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Overview + +A monorepo of small, independent AWS Lambda functions used by Dockstore ("backup and document AWS lambdas"). There is no shared build: each function has its own runtime, toolchain and tests. The SAM-based ones each have a `template.yaml` (Handler/Runtime defined there) and sample `events/`. + +| Directory | Runtime | Purpose | +|---|---|---| +| `checkUrlExists/` | Node 22 (`lambda/index.js`) | Checks a URL (http/https/ftp/sftp) is reachable; always returns 200, body is true/false | +| `cwlpack/` | Python 3.12 (`cwl_pack_function/app.py`) | Clones a git repo with pygit2 and packs a CWL descriptor with sbpack | +| `wdl-parsing/` | Java 21 (`WDLParsingFunction`, Maven) | Parses WDL descriptors | +| `nextflow-parsing/` | Java 11 template (`NextflowParsingFunction`, Maven) | Parses Nextflow descriptors | +| `cloud-watch-to-slack-testing/`, `upsertGitHubTag/` | Node (`deployment/index.js`) | Not SAM; zipped and uploaded to S3 by CircleCI. `upsertGitHubTag` relays API Gateway -> SQS -> Lambda -> Dockstore webservice | + +## Commands + +Root (JS tooling for the Node lambdas, husky and git-secrets): +- `npm ci` then `npm run lint` (eslint + prettier), `npm test` (jasmine) +- Jasmine picks up `**/deployment/*.[sS]pec.js` and `**/tests/**/test-handler.js` (see `spec/support/jasmine.json`). `checkUrlExists/lambda` has its own `package.json`: run `npm --prefix checkUrlExists/lambda ci` first. +- Single Node test: `npx jasmine path/to/test-handler.js` +- `npm run install-git-secrets` installs git-secrets; the pre-commit hook (husky) runs it. Add false positives to `.gitallowed`. + +`cwlpack` (run from `cwlpack/`, Python 3.12): +- `pip install -r tests/requirements.txt -r cwl_pack_function/requirements.txt` +- `python -m pytest tests/unit -v` (single test: `python -m pytest tests/unit/test_handler.py::`) +- `pylint cwl_pack_function` and `pylint tests` (`.pylintrc` adds the cwd to `sys.path`, so run from `cwlpack/`) + +Java lambdas (from `wdl-parsing/WDLParsingFunction` or `nextflow-parsing/NextflowParsingFunction`): +- `mvn -B clean install` (also runs checkstyle and tests in the WDL module) + +SAM (from each function's directory): `sam build --use-container`; invoke with `sam local invoke -e events/event.json` (`WDLParsingFunction`, `LambdaFunction` for checkUrlExists). `sam build` also runs the Java tests. + +## CI + +- **GitHub Actions** (`.github/workflows/maven.yml`, plus `codeql.yml`): ESLint job, then one job that builds every function with SAM in containers, invokes wdl-parsing and checkUrlExists and greps for `statusCode": 200`, and runs the cwlpack pytest/pylint steps. Runners are pinned to `ubuntu-26.04`. +- **CircleCI** (`.circleci/config.yml`): git-secrets scan, lint, jasmine tests, and SAM package + S3 upload. +- **SonarCloud** scans the workflows. Installs use `npm ci --ignore-scripts` and `pip install --only-binary :all:` with pinned versions to satisfy it; keep that pattern for new install steps. + +## Gotchas + +- Lambda runtimes and CI Python/Java versions must stay aligned (the pytest 9 Dependabot bump failed because CI was on Python 3.8). When changing a runtime, update the `template.yaml`, the workflow and the dependency pins together. +- The `cwlpack` handler returns 400 when `git_url` or `descriptor_path` query parameters are missing, or when the descriptor is missing or invalid (sbpack can raise `SystemExit` on invalid CWL). + +## Workflow conventions + +Copied from the conventions in `dockstore/dockstore`'s `CLAUDE.md` (the Dockstore-specific build/architecture sections are omitted). + +### Branching + +The repo follows Hubflow (gitflow) conventions: `develop` is the main integration branch (this repo's default +branch for PRs), with work done on `feature/*` branches branched from and merged back into `develop`, `hotfix/*` +branches for urgent fixes, and `release/*` branches cut for releases. + +### Pull requests + +When creating a PR, always create it in draft mode. A human developer must be the one to mark it ready for +review/move it out of draft state — Claude Code should not do this itself. + +Always check with the user before pushing changes to GitHub, even to a branch/PR already being worked on in +the conversation — a push can kick off a long CI build or interrupt one that's already running. + +When a GitHub MCP server or `gh` is available, diff the current work against `develop` (or whatever branch the +PR targets) and try to minimize stylistic or otherwise-minor changes that inflate the diff and make it harder +to review, unless those changes fix something a Codacy finding or other code-quality check actually flagged. + +Use `.github/PULL_REQUEST_TEMPLATE.md` for PR descriptions. Keep the freeform "Description" section brief — one +paragraph, or two for a genuinely complicated fix, not a multi-paragraph writeup — and fill "Issue" with a GitHub +issue link or `SEAB-` ticket if there is one. + +In the "Security" section, only note concerns that need extra attention from the security team (e.g. changes to +dependencies, installs, runtimes, credentials or workflow permissions); if there are none, say so briefly. Don't +reword the template's prompt text. The checklist item ("Ensure that the PR targets the correct branch") must be +copied verbatim — never reword, reformat, condense, or append explanatory text to it. Only toggle `[ ]` to `[x]` +after actually confirming it for this PR (e.g. the base branch matches the milestone/fix version of the ticket); +leave it unchecked otherwise. + +### Using CI and review feedback to guide work + +When diagnosing a failing build or iterating on an open PR, pull in whatever signal is actually available +rather than guessing: + +- If `gh` or a GitHub MCP server is available, use GitHub Actions build results (check runs, job logs) to + guide diagnosis and fixes. +- If a CircleCI MCP server is available, use its results (workflow/job status, test failures, logs) to guide + diagnosis and fixes. +- Codacy findings aren't reliably fetchable through available tooling. If Codacy results seem significant to + the task, prompt the user to copy-paste them rather than guessing at what Codacy flagged. +- Code review comments left by human developers are high-priority direction — investigate each one and + propose concrete solutions, even without an explicit instruction to do so. Bot-authored comments (Codacy, + Copilot Autofix, etc.) are useful but secondary to human reviewer comments. + +### JIRA + +When adding comments to JIRA tickets, clearly indicate that the comment was written by Claude (e.g. lead with +a line like "This comment was generated by Claude (Claude Code).").