Merge pull request #105 from algorandfoundation/update-main

Update main

Author: neilcampbell

.env.template

@@ -0,0 +1 @@
+PUYA_PATH="<ABSOLUTE_PATH_TO_PUYA>" # e.g. '/home/parallels/.local/bin/puya'

.github/workflows/gh-pages.yml

@@ -0,0 +1,35 @@
+name: 'Run typedoc and publish to pages'
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  build-and-publish-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 22.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+
+      - name: Npm install
+        run: npm ci --ignore-scripts
+
+      - name: Build doc
+        run: npm run script:documentation
+
+      - name: Upload to GitHub pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_html
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

.github/workflows/pr.yml

@@ -21,7 +21,7 @@ jobs:
         pipx install algokit --python 3.12.6
         algokit localnet reset --update
         pipx install puyapy --python 3.12.6
-      node-version: 20.x
+      node-version: 22.x
       run-build: true
       run-commit-lint: true
       audit-script: npm run audit

.github/workflows/prod-release.yml

@@ -0,0 +1,45 @@
+name: Prod Publish
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  prod_release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate bot token
+        uses: actions/create-github-app-token@v1
+        id: app_token
+        with:
+          app-id: ${{ secrets.BOT_ID }}
+          private-key: ${{ secrets.BOT_SK }}
+
+      - uses: actions/checkout@v4
+        with:
+          # Fetch entire repository history so we can determine version number from it
+          fetch-depth: 0
+          token: ${{ steps.app_token.outputs.token }}
+
+      - name: Set Git user as GitHub actions
+        run: git config --global user.email "179917785+engineering-ci[bot]@users.noreply.github.com" && git config --global user.name "engineering-ci[bot]"
+
+      - name: Merge main -> release
+        uses: devmasx/merge-branch@854d3ac71ed1e9deb668e0074781b81fdd6e771f
+        with:
+          type: now
+          from_branch: main
+          target_branch: release
+          github_token: ${{ steps.app_token.outputs.token }}
+
+      - name: Merge release -> main
+        uses: devmasx/merge-branch@854d3ac71ed1e9deb668e0074781b81fdd6e771f
+        with:
+          type: now
+          from_branch: release
+          target_branch: main
+          github_token: ${{ steps.app_token.outputs.token }}
+        env:
+          INPUT_MESSAGE: 'Merge release back to main to get version increment [no ci]'

.github/workflows/release.yml

@@ -24,7 +24,7 @@ jobs:
         pipx install algokit
         algokit localnet reset --update
         pipx install puyapy
-      node-version: 20.x
+      node-version: 22.x
       run-build: true
       run-commit-lint: true
       audit-script: npm run audit
@@ -49,10 +49,10 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.app_token.outputs.token }}
 
-      - name: Use Node.js 20.x
+      - name: Use Node.js 22.x
         uses: actions/setup-node@v4
         with:
-          node-version: 20.x
+          node-version: 22.x
 
       - run: npm ci --ignore-scripts
 
@@ -62,15 +62,26 @@ jobs:
           path: artifacts
 
       - name: Generate semantic version for @algorandfoundation/algorand-typescript-testing
+        if: github.ref_name != 'main'
         run: npx semantic-release
         env:
           GITHUB_TOKEN: ${{ steps.app_token.outputs.token }}
 
-      - name: Publish @algorandfoundation/algorand-typescript-testing
-        uses: JS-DevTools/npm-publish@v3
-        with:
-          token: ${{ secrets.NPM_TOKEN }}
-          package: artifacts/algo-ts-testing/package.json
-          access: 'public'
-          # Tagging 'main' branch with latest for now, even though it's beta because we don't have a non-beta
-          tag: ${{ github.ref_name == 'alpha' && 'alpha' || github.ref_name == 'main' && 'latest' || github.ref_name == 'release' && 'latest' || 'pre-release' }}
+      # - name: Publish @algorandfoundation/algorand-typescript-testing
+      #   if: github.ref_name != 'main'
+      #   uses: JS-DevTools/npm-publish@v3
+      #   with:
+      #     token: ${{ secrets.NPM_TOKEN }}
+      #     package: artifacts/algo-ts-testing/package.json
+      #     access: 'public'
+      #     tag: ${{ github.ref_name == 'alpha' && 'alpha' || github.ref_name == 'main' && 'beta' || github.ref_name == 'release' && 'latest' || 'pre-release' }}
+
+  # publish-docs:
+  #   name: Publish docs
+  #   needs: release
+  #   if: github.ref_name == 'release'
+  #   uses: ./.github/workflows/gh-pages.yml
+  #   permissions:
+  #     contents: read
+  #     pages: write
+  #     id-token: write

.gitignore

@@ -55,6 +55,7 @@ test-results.xml
 # Website & Code docs generation
 code-docs/
 out/
+docs/_html
 
 # dotenv environment variable files
 .env

.releaserc.json

@@ -25,6 +25,10 @@
           {
             "type": "chore",
             "release": "patch"
+          },
+          {
+            "type": "refactor",
+            "release": "patch"
           }
         ]
       }
@@ -59,6 +63,11 @@
         "pkgRoot": "artifacts/algo-ts-testing"
       }
     ],
-    "@semantic-release/github"
+    [
+      "@semantic-release/github",
+      {
+        "successComment": false
+      }
+    ]
   ]
 }

README.md

@@ -5,7 +5,7 @@
 [![github-stars](https://img.shields.io/github/stars/algorandfoundation/algorand-typescript-testing?color=74dfdc&logo=star&style=flat)](https://github.com/algorandfoundation/algorand-typescript-testing)
 [![visitor-badge](https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2Falgorandfoundation%2Falgorand-typescript-testing&countColor=%2374dfdc&style=flat)](https://github.com/algorandfoundation/algorand-typescript-testing/)
 
-`algorand-typescript-testing` is a companion package to [Algorand Typescript](https://github.com/algorandfoundation/puya-ts/tree/main/packages/algo-ts) that enables efficient unit testing of Algorand TypeScript smart contracts in an offline environment. This package emulates key AVM behaviors without requiring a network connection, offering fast and reliable testing capabilities with a familiar TypeScript interface.
+`algorand-typescript-testing` is a companion package to [Algorand Typescript](https://github.com/algorandfoundation/puya-ts/tree/main/packages/algo-ts) that enables efficient unit testing of Algorand TypeScript smart contracts in an offline environment. This package emulates key AVM behaviours without requiring a network connection, offering fast and reliable testing capabilities with a familiar TypeScript interface.
 
 The `algorand-typescript-testing` package provides:
 
@@ -42,6 +42,16 @@ npm i @algorandfoundation/algorand-typescript-testing
 
 Let's write a simple contract and test it using the `algorand-typescript-testing` framework.
 
+#### Simulating AVM
+
+`algorand-typescript-testing` includes a TypeScript transformer (`puyaTsTransformer`) that ensures contracts (with `.algo.ts` extension) and tests (with `.algo.spec.ts` or `.algo.test.ts` extensions) behave consistently between Node.js and AVM environments.
+
+The transformer replicates AVM behaviour, such as integer-only arithmetic where `3 / 2` produces `1`. For code requiring standard Node.js behaviour (e.g., `3 / 2` produces `1.5`), place it in separate `.ts` files and reference them from test files.
+
+The transformer also redirects `@algorandfoundation/algorand-typescript` imports to `@algorandfoundation/algorand-typescript-testing/internal` to provide executable implementations of Algorand TypeScript constructs like `Global`, `Box`, `Uint64`, and `clone`.
+
+If there are tests which do not need to be executed in the AVM context such as end to end tests, simply use `.test.ts` or `.spec.ts` file extensions without `.algo` part and the transformer would skip them.
+
 #### Configuring vitest
 
 If you are using [vitest](https://vitest.dev/) with [@rollup/plugin-typescript](https://www.npmjs.com/package/@rollup/plugin-typescript) plugin, configure `puyaTsTransformer` as a `before` stage transformer of the `typescript` plugin in `vitest.config.mts` file.
@@ -87,7 +97,7 @@ import { createDefaultEsmPreset, type JestConfigWithTsJest } from 'ts-jest'
 const presetConfig = createDefaultEsmPreset({})
 const jestConfig: JestConfigWithTsJest = {
   ...presetConfig,
-  testMatch: ['**/*.test.ts'],
+  testMatch: ['**/*.algo.test.ts'],
   setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
   transform: {
     '^.+\\.tsx?$': [
@@ -159,7 +169,19 @@ After the setup, the examples provided using `vitest` can be converted to work w
 #### Contract Definition
 
 ```typescript
-import { arc4, assert, Bytes, GlobalState, gtxn, LocalState, op, Txn, uint64, Uint64 } from '@algorandfoundation/algorand-typescript'
+import {
+  arc4,
+  assert,
+  Bytes,
+  GlobalState,
+  gtxn,
+  LocalState,
+  op,
+  readonly,
+  Txn,
+  uint64,
+  Uint64,
+} from '@algorandfoundation/algorand-typescript'
 
 export default class VotingContract extends arc4.Contract {
   topic = GlobalState({ initialValue: 'default_topic', key: Bytes('topic') })
@@ -185,7 +207,7 @@ export default class VotingContract extends arc4.Contract {
     return true
   }
 
-  @arc4.abimethod({ readonly: true })
+  @readonly
   public getVotes(): uint64 {
     return this.votes.value
   }
@@ -252,7 +274,7 @@ This example demonstrates key aspects of testing with `algorand-typescript-testi
 
    - Use of `arc4.Contract` as the base class for the contract.
    - ABI methods defined using the `@arc4.abimethod` decorator.
-   - Readonly method annotation with `@arc4.abimethod({readonly: true})`.
+   - Readonly method annotation with `@arc4.abimethod({readonly: true})` or `@readonly`.
 
 2. Testing ARC4 Contracts:
 
@@ -277,9 +299,9 @@ To dig deeper into the capabilities of `algorand-typescript-testing`, continue w
 
 #### Contents
 
-- [Testing Guide](./docs/testing-guide/index.md)
+- [Testing Guide](./docs/testing-guide.md)
 - [Examples](./docs/examples.md)
 - [Coverage](./docs/coverage.md)
-- [FQA](./docs/faq.md)
+- [FAQ](./docs/faq.md)
 - [API Reference](./docs/api.md)
 - [Algorand TypeScript](./docs/algots.md)

docs/algots.md

@@ -1,11 +1,13 @@
+---
+title: Algorand TypeScript
+---
+
 # Algorand TypeScript
 
-Algorand TypeScript is a partial implementation of the TypeScript programming language that runs on the Algorand Virtual Machine (AVM). It includes a statically typed framework for development of Algorand smart contracts and logic signatures, with TypeScript interfaces to underlying AVM functionality that works with standard TypeScript tooling.
+Algorand TypeScript is a partial implementation of the TypeScript programming language that runs on the Algorand Virtual Machine (AVM). It includes a statically typed framework for developing Algorand smart contracts and logic signatures, and provides TypeScript interfaces to underlying AVM functionality that work with standard TypeScript tooling.
 
-It maintains the syntax and semantics of TypeScript such that a developer who knows TypeScript can make safe assumptions
-about the behaviour of the compiled code when running on the AVM. Algorand TypeScript is also executable TypeScript that can be run
-and debugged on a Node.js virtual machine with transpilation to EcmaScript and run from automated tests.
+It preserves the syntax and semantics of TypeScript so that a developer who knows TypeScript can make safe assumptions about the behaviour of the compiled code when running on the AVM. Algorand TypeScript is also executable TypeScript that can be run and debugged on Node.js after transpilation to ECMAScript and run from automated tests.
 
-Algorand TypeScript is compiled for execution on the AVM by PuyaTs, a TypeScript frontend for the [Puya](https://github.com/algorandfoundation/puya) optimising compiler that ensures the resulting AVM bytecode execution semantics that match the given TypeScript code. PuyaTs produces output that is directly compatible with AlgoKit typed clients to make deployment and calling easy.
+Algorand TypeScript is compiled for execution on the AVM by PuyaTs, a TypeScript frontend for the [Puya](https://github.com/algorandfoundation/puya) optimising compiler. PuyaTs ensures the resulting AVM bytecode has execution semantics that match the given TypeScript code, and it produces output that is directly compatible with AlgoKit typed clients to simplify deployment and invocation.
 
-[Documentation](https://github.com/algorandfoundation/puya-ts/blob/main/README.md)
+[Documentation](https://algorandfoundation.github.io/puya-ts/index.html)

docs/api.md

@@ -1,29 +1,31 @@
+---
+title: API Reference
+---
+
 # API Reference
 
 An overview of the `algorand-typescript-testing` package - covering the main classes and functions.
 
-```{hint}
-Spotted a typo in documentation? This project is open source, please submit an issue or a PR on [GitHub](https://github.com/algorandfoundation/algorand-typescript-testing).
-```
+> Spotted a typo in the documentation? This project is open source; please submit an issue or a PR on [GitHub](https://github.com/algorandfoundation/algorand-typescript-testing).
 
 ## Contexts
 
-- [TestExecutionContext](./code/index/classes/TestExecutionContext.md)
-- [ContractContext](./code/subcontexts/contract-context/classes/ContractContext.md)
-- [LedgerContext](./code/subcontexts/ledger-context/classes/LedgerContext.md)
-- [TransactionContext](./code/subcontexts/transaction-context/classes/TransactionContext.md)
+- [TestExecutionContext](../classes/index.TestExecutionContext.html)
+- [ContractContext](../classes/index._internal_.ContractContext.html)
+- [LedgerContext](../classes/index._internal_.LedgerContext.html)
+- [TransactionContext](../classes/index._internal_.TransactionContext.html)
 
 ## Value Generators
 
-- [AvmValueGenerator](./code/value-generators/avm/classes/AvmValueGenerator.md)
-- [Arc4ValueGenerator](./code/value-generators/arc4/classes/Arc4ValueGenerator.md)
-- [TxnValueGenerator](./code/value-generators/txn/classes/TxnValueGenerator.md)
+- [AvmValueGenerator](../classes/value-generators._internal_.AvmValueGenerator.html)
+- [Arc4ValueGenerator](../classes/value-generators._internal_.Arc4ValueGenerator.html)
+- [TxnValueGenerator](../classes/value-generators._internal_.TxnValueGenerator.html)
 
 ## Utils
 
-- [addEqualityTesters](./code/index/functions/addEqualityTesters.md)
-- [encodingUtils](./code/index/variables/encodingUtil.md)
+- [addEqualityTesters](../functions/index.addEqualityTesters.html)
+- [toExternalValue](../functions/index.toExternalValue.html)
 
 ## Reference documentation
 
-We also have [auto-generated reference documentation for the code](./code/README.md).
+We also have [auto-generated reference documentation for the code](../modules/index.html).