harmonyc 0.19.0 → 0.21.0

package/AGENTS.md

@@ -0,0 +1,105 @@
+# Writing unit tests in .harmony files
+
+When writing unit tests, write them in `.harmony` files using a special structured format. This specification will be compiled to JS on-the-fly and imports the corresponding `.phrases.ts` files for step implementations.
+
+## File Structure
+
+For tests belonging to a feature, you need:
+
+- `example.harmony` - Test specifications (this file)
+- `example.phrases.ts` - Step implementations (you create this)
+
+## .harmony File Format
+
+### Syntax Rules
+
+#### Line start
+
+1. **Lines starting with `+ `** on the same level become forks, each creating a separate test case.
+2. **Lines starting with `- `** become consecutive test steps in the same test case
+3. Every other line is ignored
+
+#### Line content
+
+1. **Sections** are any line ending in `:`. It is ignored but is used for naming test cases and groups.
+2. **Steps** consist of an _action_ and an _expected outcome_ separated by `=>`.
+3. **Error steps** consist of an _action_ followed by `=> !!` and an _expected error message_ in double quotes.
+
+#### Action and Expected Outcome syntax
+
+Use human-readable phrases for both actions and expected outcomes.
+Both actions and expected outcomes can contain:
+
+- **words**
+- **punctuation** is ignored
+- **string arguments** enclosed in double quotes`"like this"`
+- **code arguments** enclosed in backticks `` `like this` ``
+
+Use string arguments for string parameters and code arguments for numbers, booleans, objects, arrays etc.
+
+If there is one obvious default action in the test case with one parameter, use an action that contains just that parameter.
+If there is one obvious default expected outcome with one parameter, use an expected outcome that contains just that parameter.
+
+### Example
+
+```harmony
+# Calculator Functions
+
+This library provides basic calculator functions.
+
++ multiply():
+  - multiply `2` and `3` => `6`
+  - multiply `-2` and `3` => `-6`
+
++ divide():
+  - divide `6` by `2` => `3`
+
+  Division by zero is an error.
+
+  + by zero:
+    We need to test both non-zero and zero dividends.
+    + divide `5` by `0` => !! "Division by zero"
+    + divide `0` by `0` => !! "Division by zero"
+```
+
+## .phrases.ts File Implementation
+
+Create a class that implements step methods corresponding to your test specifications. Use imports as needed, e.g. import the functions you are testing.
+
+`When_*` methods implement actions, and `Then_*` methods implement expected outcomes. `Then_*` methods receive
+an extra parameter, the return value of the preceding `When_*` method. Add the words and parameters from the action / expected outcome, separated by underscores, with parameters denoted by `X`,`Y`,`Z`,`A`,`B`,...
+
+Use vitest.expect in assertions.
+
+Error responses need no implementation.
+
+```typescript
+import { expect } from 'vitest'
+import { multiply, divide } from './calculator'
+
+export default class CalculatorPhrases {
+  result: number | undefined
+
+  async When_multiply_X_and_Y(a: number, b: number) {
+    return multiply(a, b)
+  }
+
+  async When_divide_X_by_Y(a: number, b: number) {
+    return divide(a, b)
+  }
+
+  async Then_X(expected: number, actual: number) {
+    expect(actual).toBe(expected)
+  }
+}
+```
+
+## Best Practices
+
+1. **Keep test descriptions clear and concise**
+2. **Group related tests using sections**
+3. **Use meaningful parameter names in method signatures, and add TypeScript types**
+4. **Store state in class properties for complex scenarios**
+5. **Handle edge cases explicitly (errors, null values, etc.)**
+6. **Use descriptive comments in-line to explain test groups**
+7. **Test both happy path and error conditions**

package/package.json

@@ -1,18 +1,8 @@
 {
   "name": "harmonyc",
   "description": "Harmony Code - model-driven BDD for Vitest",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "author": "Bernát Kalló",
-  "type": "module",
-  "bin": {
-    "harmonyc": "./cli.js"
-  },
-  "exports": {
-    "./vitest": {
-      "types": "./vitest/index.d.ts",
-      "default": "./vitest/index.js"
-    }
-  },
   "homepage": "https://github.com/harmony-ac/code#readme",
   "repository": {
     "type": "git",
@@ -21,14 +11,50 @@
   "bugs": {
     "url": "https://github.com/harmony-ac/code/issues"
   },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "harmonyc": "tsx ./src/cli/cli",
+    "test": "vitest --run",
+    "test:compile": "tsx ./src/cli/cli 'src/**/*.harmony'",
+    "dev": "vitest --watch",
+    "publish": "cp ../../README.md . && npm publish",
+    "release": "npm run test && npm run build && release publish"
+  },
+  "files": [
+    "dist",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "exports": {
+    "./vitest": {
+      "types": "./dist/vitest/index.d.ts",
+      "default": "./dist/vitest/index.js"
+    }
+  },
+  "bin": {
+    "harmonyc": "./dist/cli/cli.js"
+  },
   "dependencies": {
     "fast-glob": "^3.3.2",
     "tinyrainbow": "1",
+    "ts-morph": "^27.0.2",
     "typescript-parsec": "0.3.4"
   },
   "optionalDependencies": {
     "watcher": "^2.3.1"
   },
+  "devDependencies": {
+    "@ossjs/release": "^0.10.0",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^22.10.6",
+    "expect": "^29.7.0",
+    "tsx": "^4.7.1",
+    "typescript": "^5.3.3",
+    "vite": "^7.1.10",
+    "vitest": "^3.2.4"
+  },
   "license": "MIT",
   "keywords": [
     "unit test",
@@ -46,4 +72,4 @@
     "test modelling",
     "vitest"
   ]
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024-2025 Bernát Kalló
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.