Skip to content

Commit 3811bba

Browse files
cblanqueracblanquera
committed
first pass on target strategy
1 parent cee3cf7 commit 3811bba

80 files changed

Lines changed: 5564 additions & 1150 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.

‎.github/workflows/build-binaries.yml‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
name: Build and Release Binaries
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
workflow_dispatch:
8+
9+
jobs:
10+
build:
11+
strategy:
12+
fail-fast: false
13+
matrix:
14+
settings:
15+
- host: macos-latest
16+
target: x86_64-apple-darwin
17+
build: yarn build:rs --target x86_64-apple-darwin
18+
- host: macos-latest
19+
target: aarch64-apple-darwin
20+
build: yarn build:rs --target aarch64-apple-darwin
21+
- host: windows-latest
22+
target: x86_64-pc-windows-msvc
23+
build: yarn build:rs --target x86_64-pc-windows-msvc
24+
- host: windows-latest
25+
target: i686-pc-windows-msvc
26+
build: yarn build:rs --target i686-pc-windows-msvc
27+
- host: ubuntu-latest
28+
target: x86_64-unknown-linux-gnu
29+
build: yarn build:rs --target x86_64-unknown-linux-gnu
30+
- host: ubuntu-latest
31+
target: x86_64-unknown-linux-musl
32+
build: |
33+
sudo apt-get update
34+
sudo apt-get install musl-tools
35+
yarn build:rs --target x86_64-unknown-linux-musl
36+
- host: ubuntu-latest
37+
target: aarch64-unknown-linux-gnu
38+
build: |
39+
sudo apt-get update
40+
sudo apt-get install gcc-aarch64-linux-gnu
41+
yarn build:rs --target aarch64-unknown-linux-gnu
42+
- host: ubuntu-latest
43+
target: i686-unknown-linux-gnu
44+
build: |
45+
sudo apt-get update
46+
sudo apt-get install gcc-multilib
47+
yarn build:rs --target i686-unknown-linux-gnu
48+
- host: ubuntu-latest
49+
target: armv7-unknown-linux-gnueabihf
50+
build: |
51+
sudo apt-get update
52+
sudo apt-get install gcc-arm-linux-gnueabihf
53+
yarn build:rs --target armv7-unknown-linux-gnueabihf
54+
- host: ubuntu-latest
55+
target: x86_64-unknown-freebsd
56+
build: yarn build:rs --target x86_64-unknown-freebsd
57+
58+
name: Build ${{ matrix.settings.target }}
59+
runs-on: ${{ matrix.settings.host }}
60+
61+
steps:
62+
- uses: actions/checkout@v4
63+
64+
- name: Setup Node.js
65+
uses: actions/setup-node@v4
66+
with:
67+
node-version: '18'
68+
cache: 'yarn'
69+
70+
- name: Setup Rust
71+
uses: dtolnay/rust-toolchain@stable
72+
with:
73+
targets: ${{ matrix.settings.target }}
74+
75+
- name: Cache cargo
76+
uses: actions/cache@v4
77+
with:
78+
path: |
79+
~/.cargo/registry/index/
80+
~/.cargo/registry/cache/
81+
~/.cargo/git/db/
82+
.cargo-cache
83+
target/
84+
key: ${{ matrix.settings.target }}-cargo-${{ hashFiles('**/Cargo.lock') }}
85+
86+
- name: Install dependencies
87+
run: yarn install --frozen-lockfile
88+
89+
- name: Build binary
90+
run: ${{ matrix.settings.build }}
91+
92+
- name: Upload binary
93+
uses: actions/upload-artifact@v4
94+
with:
95+
name: binaries-${{ matrix.settings.target }}
96+
path: |
97+
*.node
98+
cjs/*.node
99+
esm/*.node
100+
101+
release:
102+
name: Create Release
103+
runs-on: ubuntu-latest
104+
needs: build
105+
if: startsWith(github.ref, 'refs/tags/')
106+
107+
steps:
108+
- uses: actions/checkout@v4
109+
110+
- name: Download all artifacts
111+
uses: actions/download-artifact@v4
112+
with:
113+
path: artifacts
114+
115+
- name: Create Release
116+
id: create_release
117+
uses: actions/create-release@v1
118+
env:
119+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
120+
with:
121+
tag_name: ${{ github.ref }}
122+
release_name: Release ${{ github.ref }}
123+
draft: false
124+
prerelease: false
125+
126+
- name: Upload Release Assets
127+
run: |
128+
for dir in artifacts/binaries-*; do
129+
target=$(basename "$dir" | sed 's/binaries-//')
130+
for file in "$dir"/*.node; do
131+
if [ -f "$file" ]; then
132+
asset_name="idea-parser-${target}.node"
133+
echo "Uploading $file as $asset_name"
134+
curl \
135+
-X POST \
136+
-H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
137+
-H "Content-Type: application/octet-stream" \
138+
--data-binary @"$file" \
139+
"https://uploads.github.com/repos/${{ github.repository }}/releases/${{ steps.create_release.outputs.id }}/assets?name=$asset_name"
140+
fi
141+
done
142+
done

‎.github/workflows/test.yml‎

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,6 @@ jobs:
99
uses: actions/setup-node@v4
1010
with:
1111
node-version: '20.x'
12-
- name: Set up Rust
13-
uses: dtolnay/rust-toolchain@stable
14-
with:
15-
components: llvm-tools-preview
16-
- name: Install cargo-llvm-cov
17-
uses: taiki-e/install-action@cargo-llvm-cov
1812
- name: Install dependencies
1913
run: yarn
2014
- name: Building Code
@@ -24,6 +18,4 @@ jobs:
2418
- name: Coveralls
2519
uses: coverallsapp/github-action@v2
2620
with:
27-
files: coverage/lcov.info packages/idea-rust/coverage/lcov.info
28-
format: lcov
29-
github-token: ${{ secrets.GITHUB_TOKEN }}
21+
github-token: ${{ secrets.GITHUB_TOKEN }}

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -146,16 +146,18 @@ cjs/
146146
example/src/enums.ts
147147
packages/idea-language/client/package-lock.json
148148
packages/idea-language/server/package-lock.json
149-
packages/idea-transformer/tests/out
149+
packages/idea-node/tests/out
150150
# Rust
151151
packages/idea-rust/target/
152152
packages/idea-rust/Cargo.lock
153153
packages/idea-rust/coverage/
154154
# Node native addon output
155155
packages/idea-node/dist/
156156
packages/idea-node/*.node
157+
packages/idea-node-*/idea_node.*.node
157158
packages/idea-node/index.js
158159
packages/idea-node/index.d.ts
160+
packages/idea-node/loader.js
159161
.DS_Store
160162

161163
.clinerules

‎AGENTS.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# AGENTS
2+
3+
## Workspace Summary
4+
5+
- `packages/idea-rust`
6+
- Canonical parser implementation in Rust.
7+
- Node native binding crate lives under `crates/idea_parser_node`.
8+
- `packages/idea-node`
9+
- Main Node package.
10+
- Owns the TypeScript API, transformer, terminal, CLI, and native loader boundary.
11+
- Supports both ESM and CJS build outputs.
12+
- `packages/idea-node-*`
13+
- Platform-specific native binary packages for npm distribution.
14+
- These are publishable package directories, but they are intentionally not
15+
part of the active Yarn workspaces list because Yarn v1 will try to install
16+
incompatible targets on the local host.
17+
- `language`
18+
- Intentionally not part of the Yarn workspace.
19+
20+
## idea-node Rules
21+
22+
- Public TypeScript source lives in `packages/idea-node/src`.
23+
- The root native loader boundary lives outside `src`.
24+
- Keep `loader.cjs` tracked.
25+
- Keep `loader.d.cts` tracked.
26+
- `Parser` should not own platform probing logic.
27+
- `Parser` wraps native calls and normalizes errors.
28+
- Native binary resolution belongs in the root loader.
29+
- Prefer keeping the top-level API in `src/index.ts` aligned with:
30+
- `tokenize()`
31+
- `parse()`
32+
- `parseAst()`
33+
- `final()`
34+
- `Parser`
35+
- `Transformer`
36+
- `Terminal`
37+
38+
## Build Artifacts
39+
40+
- Do not commit generated root `napi` stubs.
41+
- Ignore these generated files in `packages/idea-node`:
42+
- `index.js`
43+
- `index.d.ts`
44+
- `loader.js`
45+
- The tracked root files should be:
46+
- `loader.cjs`
47+
- `loader.d.cts`
48+
- Root `.node` binaries in `packages/idea-node` are treated as local build
49+
artifacts that get mirrored into the matching platform package.
50+
51+
## Coverage Notes
52+
53+
- JS coverage currently counts the root CommonJS loader if it is included in the test run.
54+
- Rust coverage is generated separately with `cargo llvm-cov`.
55+
- `loader.cjs` is intentionally excluded from JS coverage.
56+
57+
## Native Packaging
58+
59+
- `packages/idea-node` is the wrapper package that consumers install.
60+
- Platform binaries are distributed through optional dependencies such as:
61+
- `idea-node-darwin-arm64`
62+
- `idea-node-linux-x64-gnu`
63+
- `idea-node-win32-x64-msvc`
64+
- In repo development, `packages/idea-node/package.json` uses local `file:`
65+
optional dependencies so the loader fallback can be tested before publishing.
66+
- Before publishing to npm, those `file:` optional dependencies should be
67+
rewritten to versioned package references.
68+
69+
## Native Build Flow
70+
71+
- Current host build:
72+
- `yarn --cwd packages/idea-node build`
73+
- This runs:
74+
- `build:native`
75+
- `sync:platform-package`
76+
- TypeScript builds for `cjs` and `esm`
77+
- package metadata generation for `cjs/package.json` and `esm/package.json`
78+
- `build:native` uses:
79+
- `napi build --platform --cargo-cwd ../idea-rust/crates/idea_parser_node`
80+
- `sync:platform-package` mirrors any locally built root binary from
81+
`packages/idea-node` into the matching `packages/idea-node-*` directory.
82+
83+
## Cross-Platform Binary Builds
84+
85+
- Building every OS package from one machine is not realistic for all targets.
86+
- The practical model is one build job per target environment:
87+
- macOS arm64 builds `idea_node.darwin-arm64.node`
88+
- macOS x64 builds `idea_node.darwin-x64.node`
89+
- Linux x64 glibc builds `idea_node.linux-x64-gnu.node`
90+
- Linux x64 musl builds `idea_node.linux-x64-musl.node`
91+
- Windows x64 MSVC builds `idea_node.win32-x64-msvc.node`
92+
- and so on
93+
- For each target job:
94+
- run `yarn --cwd packages/idea-node build`
95+
- collect the generated `.node` file
96+
- place or publish it in the matching `packages/idea-node-*` package
97+
- The in-repo sync script only mirrors binaries that were actually built on the
98+
current machine; it does not cross-compile unsupported targets by itself.
99+
100+
## Style Notes
101+
102+
- TypeScript should follow the repo style guide shared in chat:
103+
- 2-space indentation
104+
- single quotes
105+
- semicolons
106+
- separate type imports from runtime imports
107+
- JSDoc for public members
108+
- comments explain why, not what
109+
- export ordering:
110+
- types
111+
- constants
112+
- functions
113+
- classes
114+
- default export last

‎README.md‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<div align="center">
22
<h1>💡 Idea</h1>
3-
<a href="https://www.npmjs.com/package/@stackpress/idea"><img src="https://img.shields.io/npm/v/@stackpress/idea.svg?style=flat" /></a>
3+
<a href="https://www.npmjs.com/package/@stackpress/idea-node"><img src="https://img.shields.io/npm/v/@stackpress/idea-node.svg?style=flat" /></a>
44
<a href="https://github.com/stackpress/idea/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat" /></a>
55
<a href="https://github.com/stackpress/idea/commits/main/"><img src="https://img.shields.io/github/last-commit/stackpress/idea" /></a>
66
<a href="https://github.com/stackpress/idea/actions"><img src="https://img.shields.io/github/actions/workflow/status/stackpress/idea/test.yml" /></a>
@@ -118,7 +118,11 @@ Automatically generate:
118118

119119
Here's how a simple e-commerce schema transforms into a full application:
120120

121+
<<<<<<< HEAD
121122
```js
123+
=======
124+
```idea
125+
>>>>>>> da5198c (outlining docs)
122126
// schema.idea
123127
enum UserRole {
124128
ADMIN "Administrator"
@@ -212,14 +216,18 @@ This workflow enables rapid prototyping and development, making it possible to g
212216
### 1. Installation
213217

214218
```bash
215-
$ npm i -D @stackpress/idea
219+
$ npm i -D @stackpress/idea-node
216220
```
217221

218222
### 2. Create Your First Schema
219223

220224
Create a `schema.idea` file:
221225

226+
<<<<<<< HEAD
222227
```js
228+
=======
229+
```idea
230+
>>>>>>> da5198c (outlining docs)
223231
model User {
224232
id String @id @default("nanoid()")
225233
name String @required
@@ -249,6 +257,15 @@ This documentation is organized into several sections:
249257
### 📋 [Specifications](https://github.com/stackpress/idea/blob/main/docs/Specifications.md)
250258
Complete reference for the `.idea` file format syntax, data types, and schema structure.
251259

260+
<<<<<<< HEAD
261+
=======
262+
### 🔧 [Parser Documentation](https://github.com/stackpress/idea/blob/main/docs/api/parser/)
263+
Technical documentation for the parser library that processes `.idea` files.
264+
265+
### 🔄 [Transformer Documentation](https://github.com/stackpress/idea/blob/main/docs/api/transformer/)
266+
Documentation for the transformer library that executes plugins and generates code.
267+
268+
>>>>>>> da5198c (outlining docs)
252269
### 🔌 [Plugin Development](https://github.com/stackpress/idea/blob/main/docs/plugins/)
253270
Comprehensive guides for creating custom plugins, including tutorials for:
254271
- Database schema generators

0 commit comments

Comments
 (0)