Feature Request: Import Path Mapping (TypeScript-style)

[NickNekilov]

Motivation

In large smart-contract systems, contracts are often split across multiple modules and directories.
Currently, imports require relative paths, which quickly become cumbersome and fragile:

import "../../common/jettons"
import "../../common/utils"
import "../../../../third_party/jest-tolk/testing"

This leads to:

• Hard-to-read imports with lots of ../..
• Fragility when files are moved or refactored
• Repetition across multiple contracts in the same project

Proposed Solution

Introduce path mapping (similar to TypeScript’s paths), allowing developers to define import aliases in a project config (e.g. tolk.json):

{
  "paths": {
    "@*": [
      "contracts/*",
      "third_party/*"
    ]
  }
}

With this feature, imports become shorter and more elegant:

import "@common/jettons"
import "@common/utils"
import "@jest-tolk/testing"

Benefits

• Readability: Cleaner, shorter import statements
• Maintainability: Less risk of broken imports after refactoring file structure
• Consistency: Developers can share common alias mappings across projects
• Ecosystem growth: Third-party libraries (like jest-tolk) can be imported with simple, predictable names

Alternatives Considered

• Continuing with relative paths → quickly becomes unmanageable in big repos
• Hard-coding a lib/ or std/ directory → too restrictive for multi-package projects

Implementation Notes

• Path resolution can follow the same priority system as TypeScript (check paths aliases first, then fallback to relative resolution).
• A single alias (@*) can expand to multiple directories (first match wins).
• Should integrate naturally with existing build tools and IDE integrations.

[TrueCarry]

I like the idea, but I think we need to add few more details to the proposal while we can.

• node_modules should be added to path by default, with option to disable that behaviour if user needs to.
• Packages from node_modules COULD NOT be imported without explicit version in the path
  For example if we want to use @ston-fi/funcbox, we need to import is as

import "@ston-fi/funcbox@0.1.9/contracts/consts.fc"

Since we're working with smart contracts, reproducibility is very important and we can't allow arbitrary package versions. Resolver will check package version on disk with the one specified in the import and will only proceed it they match.

Potential improvements:

• Allow to specify commit hash for git submodule or zip hash for imports from zip folders