foreign-thon-old/docs/contributing.md

Contributing

Project structure

foreignthon/
├── packages/
│   ├── foreignthon/               # core engine + fpy CLI
│   │   ├── src/foreignthon/
│   │   │   ├── cli.py             # fpy commands
│   │   │   ├── transpiler.py      # tokenizer-based transpiler + @@ pre-pass
│   │   │   ├── pack.py            # language pack loader + entry point discovery
│   │   │   └── errors.py          # bilingual error hook
│   │   └── tests/
│   └── langs/
│       ├── es/                    # foreignthon-es (Spanish)
│       └── ta/                    # foreignthon-ta (Tamil)
|       |__ ch/
├── docs/
└── .gitea/workflows/
├── ci.yml                     # runs tests + lint on every push
└── publish.yml                # builds + publishes to PyPI on git tag

How the transpiler works

1. Pre-pass — scans for @@keyword postfix syntax and rewrites lines to prefix form
2. Tokenizer — uses Python's tokenize module to swap NAME tokens. Strings and comments are never touched.
3. Runner — compiles with the original filename so tracebacks point to your .es.py file, not a temp file

Setup

python -m venv .venv && source .venv/bin/activate
pip install -e "packages/foreignthon[dev]"
pip install -e packages/langs/es
pip install -e packages/langs/ta
pip install -e packages/langs/ch

Running tests

pytest packages/foreignthon/tests/ -v

Linting

ruff check packages/foreignthon/src

Adding a language pack

See language-packs.md for the full guide.

CI

Every push to main runs tests and lint (non-blocking). Releases are triggered by pushing a git tag — see releasing.md.

Submitting changes

1. Fork the repo
2. Create a branch
3. Make your changes + add tests if relevant
4. Open a pull request against main