Skip to content

Commit a3a260a

Browse files
greenc-FNALgreenc-FNAL
committed
Devcontainer config and context for kiro-cli (Amazon)
1 parent d2325fb commit a3a260a

File tree

6 files changed

+521
-1
lines changed

6 files changed

+521
-1
lines changed

‎.devcontainer/devcontainer.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@
2323
"source=${localEnv:HOME}/.podman-proxy/podman.sock,target=/tmp/podman.sock,type=bind",
2424
"source=${localEnv:HOME}/.aws,target=/root/.aws,type=bind",
2525
"source=${localEnv:HOME}/.config/gh,target=/root/.config/gh,type=bind,readonly",
26-
"source=${localEnv:HOME}/.gnupg,target=/root/.gnupg,type=bind"
26+
"source=${localEnv:HOME}/.gnupg,target=/root/.gnupg,type=bind",
27+
"source=${localEnv:HOME}/.kiro,target=/root/.kiro,type=bind"
2728
],
2829
"initializeCommand": "bash .devcontainer/ensure-repos.sh",
2930
"onCreateCommand": "bash .devcontainer/setup-repos.sh /workspaces",

‎.devcontainer/post-create.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,6 @@ if command -v prek >/dev/null 2>&1; then
1717
elif command -v pre-commit >/dev/null 2>&1; then
1818
pre-commit install || true
1919
fi
20+
21+
# Install kiro-cli and set up shell integrations.
22+
curl -fsSL https://cli.kiro.dev/install | bash

‎.kiro/rules/guidelines.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# Development Guidelines
2+
3+
## File Formatting — CRITICAL (applies to every file you create or edit)
4+
5+
- Files must end with exactly one newline (`\n`). No trailing blank lines, no
6+
trailing whitespace on any line (including blank lines within the file).
7+
- The final character must be `\n`; the character before it must not be `\n`
8+
or a space/tab.
9+
10+
## Language-Specific Formatting
11+
12+
### C++
13+
14+
- clang-format (`.clang-format`): 100-char line limit, 2-space indentation
15+
- clang-tidy (`.clang-tidy`): follow all recommendations
16+
- Header files: `.hpp`; implementation files: `.cpp`
17+
- Test files: `*_test.cpp` or descriptive names
18+
19+
### Python
20+
21+
- ruff for formatting and linting (`pyproject.toml`)
22+
- Google-style docstrings; 99-char line limit; double quotes; type hints
23+
- Test files: `test_*.py`
24+
- Do not name files after standard library modules (e.g., avoid `types.py`)
25+
26+
### CMake
27+
28+
- gersemi or cmake-format: `dangle_align: "child"`, `dangle_parens: true`
29+
30+
### Jsonnet
31+
32+
- jsonnetfmt for formatting; CI enforces this
33+
- Used for workflow configs in `test/` and elsewhere
34+
35+
### Markdown
36+
37+
- MD012: no multiple consecutive blank lines
38+
- MD022: headings surrounded by one blank line
39+
- MD031: fenced code blocks surrounded by one blank line
40+
- MD032: lists surrounded by one blank line
41+
- MD034: no bare URLs — use `[text](url)`
42+
- MD036: use `#` headings, not `**Bold**` for titles
43+
- MD040: always specify code block language
44+
45+
## Naming Conventions
46+
47+
### C++
48+
49+
- `lowercase_snake_case` for types, classes, functions, variables
50+
- `UPPER_CASE` for macros and constants
51+
- Namespaces: `phlex::` (core), `phlex::experimental::` (experimental)
52+
53+
### Python
54+
55+
- PEP 8; descriptive test function names
56+
57+
## Comments and Documentation
58+
59+
- Explain *why*, not *what* or *how* — code is self-documenting for those
60+
- No temporal markers (`NEW:`, `CHANGED:`) — git history tracks changes
61+
- Remove dead code; do not comment it out
62+
- If an expected feature is absent, explain why (e.g., "Single-threaded
63+
context; locks unnecessary")
64+
65+
## Git Workflow
66+
67+
### Branch Creation
68+
69+
Do not set upstream tracking at branch creation time:
70+
71+
```bash
72+
git checkout -b feature/my-feature # no --track
73+
git switch --no-track -c feature/my-feature # alternative
74+
```
75+
76+
Set tracking only when pushing for the first time:
77+
78+
```bash
79+
git push -u origin feature/my-feature
80+
```
81+
82+
### Pull Requests
83+
84+
- Pass all CI checks; follow coding guidelines
85+
- Minimize changes — keep PRs focused
86+
- If changes affect `phlex-examples`, create an issue there (or in `phlex`
87+
if not possible), and notify the user
88+
- If changes require documentation updates in `phlex-design`, create an issue
89+
there (or in `phlex` if not possible)
90+
- If changes affect Spack recipes in `phlex-spack-recipes`, create an issue
91+
there (or in `phlex` if not possible)
92+
93+
## Build and Test Workflow
94+
95+
### Environment Setup
96+
97+
Always source `setup-env.sh` before building or testing. This applies in all
98+
environments (devcontainer, local, HPC, CI containers):
99+
100+
```bash
101+
# Standalone repository
102+
. scripts/setup-env.sh
103+
104+
# Multi-project workspace (workspace root contains setup-env.sh)
105+
. srcs/phlex/scripts/setup-env.sh
106+
```
107+
108+
### Build
109+
110+
```bash
111+
# Preferred: use presets
112+
cmake --preset default -S . -B build
113+
ninja -C build
114+
115+
# Or manually
116+
cmake -B build -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo -G Ninja
117+
cmake --build build -j $(nproc)
118+
```
119+
120+
### Test
121+
122+
```bash
123+
ctest --test-dir build -j $(nproc) --output-on-failure
124+
# With timeout guard (recommended):
125+
ctest --test-dir build -j $(nproc) --test-timeout 90
126+
# Run specific tests:
127+
ctest --test-dir build -R "regex"
128+
```
129+
130+
### Coverage
131+
132+
```bash
133+
# Complete workflow
134+
./scripts/coverage.sh all
135+
136+
# Step by step
137+
./scripts/coverage.sh setup test html view
138+
139+
# Via CMake targets (after coverage preset build)
140+
cmake --build build --target coverage-xml
141+
cmake --build build --target coverage-html
142+
```
143+
144+
### Pre-commit Hooks
145+
146+
```bash
147+
# Detect available tool
148+
PREKCOMMAND=$(command -v prek || command -v pre-commit || echo "")
149+
150+
# Install hooks (once per clone; automatic in devcontainer)
151+
$PREKCOMMAND install
152+
153+
# Run all hooks against all files (recommended before opening a PR)
154+
$PREKCOMMAND run --all-files
155+
156+
# Run against changed files only
157+
$PREKCOMMAND run
158+
159+
# Update hook revisions
160+
$PREKCOMMAND auto-update
161+
```
162+
163+
`prek` is installed in `phlex-dev`; not in `phlex-ci`. Fall back to invoking
164+
formatters directly if neither is available.
165+
166+
## Python Integration Details
167+
168+
- `PYTHONPATH` should include only paths containing user Python modules loaded
169+
by Phlex (source dir and build output dir). Do not append system/Spack/venv
170+
`site-packages`.
171+
- Type conversion in `plugins/python/src/modulewrap.cpp` uses substring
172+
matching on type names — this is brittle. Ensure converters exist for all
173+
types used in tests. Exact matches required (`numpy.float32 != float`).
174+
- Python test structure: C++ driver provides data streams, Jsonnet config
175+
wires the graph, Python script implements algorithms.
176+
177+
## Memory Management
178+
179+
- `std::shared_ptr` for shared ownership; `std::unique_ptr` for exclusive
180+
- Raw pointers only for non-owning references
181+
- Python/C++ interop: manual `Py_INCREF`/`Py_DECREF`; `PyGILRAII` for GIL
182+
- GC-tracked Python types: `Py_TPFLAGS_HAVE_GC`, implement `tp_traverse` and
183+
`tp_clear`, call `PyObject_GC_UnTrack` before deallocation
184+
185+
## Error Handling
186+
187+
- C++: `std::runtime_error` for runtime failures; propagate Python exceptions
188+
as `std::runtime_error`
189+
- Python C API: set exceptions with `PyErr_SetString`/`PyErr_Format`; return
190+
`nullptr` on error; clear with `PyErr_Clear()` when recovering
191+
192+
## External Software Versions
193+
194+
When specifying versions or commit hashes for external software (e.g., GitHub
195+
Actions), always verify against the official release source:
196+
197+
1. Check existing workflows in `.github/workflows/` for the version currently
198+
in use
199+
2. Verify whether a newer version exists at the official releases page
200+
3. The authoritative source always takes precedence over training data
201+
202+
## Platform-Specific Code
203+
204+
```cpp
205+
#if __linux__
206+
constexpr double mem_denominator{1e3};
207+
#else // AppleClang
208+
constexpr double mem_denominator{1e6};
209+
#endif
210+
```
211+
212+
Use POSIX APIs where available; document platform requirements.
213+
214+
## Searching Source Directories
215+
216+
If the workspace root contains a `srcs/` directory with symbolic links, always
217+
use `find -L` or `find -follow` to ensure linked directories are traversed.

‎.kiro/rules/product.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Product Overview
2+
3+
## Purpose
4+
5+
Phlex is a framework for **P**arallel, **h**ierarchical, and **l**ayered
6+
**ex**ecution of data-processing algorithms. It provides a graph-based
7+
execution engine for orchestrating complex data-processing workflows with
8+
automatic parallelization, hierarchical data organization, and layered
9+
algorithm execution.
10+
11+
## Repository Ecosystem
12+
13+
- **Primary**: `Framework-R-D/phlex` — this repository
14+
- **Design & docs**: `Framework-R-D/phlex-design`
15+
- **Coding guidelines**: `Framework-R-D/phlex-coding-guidelines`
16+
- **Examples**: `Framework-R-D/phlex-examples`
17+
- **Spack recipes**: `Framework-R-D/phlex-spack-recipes`
18+
- **Build system dependency**: `FNALssi/cetmodules`
19+
- **Container images**: `phlex-ci` (CI), `phlex-dev` (devcontainer / local dev)
20+
21+
## Key Features
22+
23+
- Graph-based workflow execution with automatic parallelization via Intel TBB
24+
- Algorithm types: providers, transforms, observers, filters, folds, unfolds
25+
- Hierarchical data processing with configurable data-layer hierarchies
26+
- Product store for type-safe data sharing between algorithms
27+
- Jsonnet-based workflow configuration
28+
- Python plugin support via C API (and optional cppyy)
29+
- Optional FORM integration for ROOT-based data persistence
30+
31+
## Target Users
32+
33+
Scientific computing researchers and data-pipeline engineers building
34+
parallel, hierarchical data-processing workflows — primarily in high-energy
35+
physics.
36+
37+
## Status
38+
39+
- Version: 0.1.0 (active development)
40+
- License: Apache 2.0
41+
- Repository: <https://github.com/Framework-R-D/phlex>
42+
- Coverage: tracked via Codecov

‎.kiro/rules/structure.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Project Structure
2+
3+
## Source Layout
4+
5+
```text
6+
phlex/ # C++ framework source
7+
app/ # Main executable and CLI
8+
core/ # Execution engine, graph, algorithm declarations
9+
fold/ # Fold operation implementations
10+
detail/ # Internal implementation details
11+
model/ # Data model and type system
12+
graph/ # Graph execution nodes
13+
metaprogramming/ # Template metaprogramming utilities
14+
utilities/ # Resource monitoring, hashing, async helpers
15+
form/ # Optional FORM/ROOT data persistence layer
16+
core/ # Placement, token management
17+
form/ # Main FORM interface and config
18+
persistence/ # Persistence layer
19+
storage/ # Storage backends
20+
root_storage/ # ROOT TFile/TTree/TBranch wrappers
21+
util/ # Factory patterns
22+
plugins/ # Extensibility layer
23+
python/ # Python plugin (C API + NumPy)
24+
src/ # C++ implementation (modulewrap.cpp, lifelinewrap.cpp)
25+
python/ # Python package code
26+
layer_generator.cpp/hpp # Code generation for data layers
27+
generate_layers.cpp # Layer generation tool
28+
test/ # Test suite
29+
benchmarks/ # Performance benchmarks
30+
demo-giantdata/ # Large-scale data processing demos
31+
form/ # FORM integration tests
32+
max-parallelism/ # Parallelism tests
33+
memory-checks/ # Memory usage tests
34+
mock-workflow/ # Mock workflow for testing
35+
plugins/ # Plugin system tests
36+
python/ # Python integration tests
37+
tbb-preview/ # TBB preview feature tests
38+
utilities/ # Utility tests
39+
*.cpp # Core unit tests
40+
scripts/ # Development and CI automation
41+
setup-env.sh # Environment setup (multi-mode: standalone/workspace/Spack)
42+
coverage.sh # Coverage workflow automation
43+
fix_header_guards.py # C++ header guard fixer
44+
normalize_coverage_xml.py
45+
normalize_coverage_lcov.py
46+
export_llvm_lcov.py
47+
create_coverage_symlinks.py
48+
check_codeql_alerts.py
49+
README.md # Detailed setup documentation
50+
QUICK_REFERENCE.md # Quick-start commands
51+
Modules/ # CMake modules
52+
private/ # Internal build utilities
53+
ci/ # CI container definitions
54+
Dockerfile # phlex-ci image
55+
spack.yaml # Spack environment for CI
56+
dev/
57+
jules/ # Jules AI agent environment
58+
Dockerfile # Ubuntu 24.04 test image
59+
prepare-environment.sh
60+
README.md
61+
.devcontainer/ # VS Code devcontainer configuration
62+
.github/
63+
workflows/ # CI/CD pipelines
64+
actions/ # Reusable GitHub Actions
65+
copilot-instructions.md # GitHub Copilot guidelines
66+
.kiro/
67+
rules/ # Kiro AI agent guidelines (this tree)
68+
.amazonq/
69+
rules/ # Amazon Q guidelines
70+
```
71+
72+
## Codespace / Devcontainer Layout
73+
74+
In a GitHub Codespace or devcontainer, companion repositories are cloned
75+
automatically alongside the primary repository:
76+
77+
```text
78+
/workspaces/phlex # primary repository (workspace root)
79+
/workspaces/phlex-design # design documentation
80+
/workspaces/phlex-examples # example programs
81+
/workspaces/phlex-coding-guidelines # contributor coding guidelines
82+
/workspaces/phlex-spack-recipes # Spack recipes
83+
```
84+
85+
Open `.devcontainer/codespace.code-workspace` for a multi-root VS Code window.
86+
Git hooks are installed automatically via `postCreateCommand` (`prek install`).
87+
88+
## Key Files
89+
90+
| File | Purpose |
91+
| ---- | ------- |
92+
| `CMakeLists.txt` | Top-level build definition |
93+
| `CMakePresets.json` | Build presets (default, coverage-gcc, coverage-clang) |
94+
| `pyproject.toml` | Python tool configuration (ruff, mypy) |
95+
| `.clang-format` | C++ formatting rules (100-char limit, 2-space indent) |
96+
| `.clang-tidy` | C++ static analysis rules |
97+
| `.gersemirc` | CMake formatting rules |
98+
| `.cmake-format.json` | cmake-format rules |
99+
| `.markdownlint.jsonc` | Markdown linting rules |
100+
| `.prettierrc.yaml` | YAML formatting rules |
101+
| `.pre-commit-config.yaml` | Pre-commit hook configuration |
102+
| `.actrc` | Local `act` configuration for GitHub Actions |
103+
| `codecov.yml` | Codecov configuration |
104+
| `scripts/setup-env.sh` | Environment setup script |
105+
106+
## Architectural Patterns
107+
108+
- **Graph-based execution**: DAG of algorithm nodes, automatic dependency
109+
resolution, parallel execution via Intel TBB
110+
- **Product store**: Central type-safe data product storage; algorithms
111+
communicate through it rather than directly
112+
- **Plugin architecture**: Dynamic module loading; users extend the framework
113+
without modifying core code
114+
- **Hierarchical data model**: Multi-level data organization
115+
(e.g., run → subrun → event)
116+
- **Type erasure**: Template-based heterogeneous algorithm collections
117+
- **Configuration as code**: Jsonnet-based workflow definition with
118+
inheritance and composition

0 commit comments

Comments
 (0)