Expand LSP capabilities, add full Go ASN.1 frontend, and broaden CI coverage

.github/workflows/ci.yml

@@ -8,16 +8,33 @@ on:
 
 jobs:
   test:
+    # Run the same suite on Linux, macOS, and Windows. Windows uses
+    # backslash as its path separator and is case-insensitive for file
+    # names, both of which used to trip up path-handling tests until
+    # the cleanup tracked in issue #629.
     name: Tests
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
     steps:
+      # The TTCN-3 conformance test suite under
+      # testdata/ttcn3-conformance-tests/ has paths > 260 chars,
+      # which trips Windows' MAX_PATH limit during checkout. This
+      # config must run BEFORE actions/checkout so the clone itself
+      # can write the long paths.
+      - name: Enable Git long paths (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: git config --system core.longpaths true
       - uses: actions/checkout@v4
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
           go-version: stable
       - name: Test
-        run: go test -race -v ./...
+        run: go test -race ./...
 
   lint:
     name: Linting

README.md

@@ -101,6 +101,13 @@ You may control installation by specifying PREFIX and DESTDIR variables. For exa
 	make install DESTDIR=$HOME/.local
 
 
+# Getting started
+
+For a five-minute, end-to-end walkthrough that takes you from "I just
+installed ntt" to running a TTCN-3 test in your editor, see
+[docs/getting-started.md](docs/getting-started.md).
+
+
 # Contact us
 
 If you have questions, you are welcome to contact us at
@@ -122,3 +129,13 @@ automation environment.
 ## License
 
 This project is licensed under the BSD-3-Clause license - see the [LICENSE](https://github.com/nokia/ntt/blob/master/LICENSE).
+
+## Acknowledgements
+
+Parts of ntt's architecture (the pure-Go ASN.1 frontend, the
+Wadler-style formatter combinators, the schema-driven AST generator
+and the lint Rule lifecycle) were inspired by
+[Vanadium](https://github.com/makekryl/vanadium) by Mikhail Krylov.
+Vanadium is BSD-3-licensed; see
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for the full notice
+and a list of the borrowed concepts.

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,63 @@
+# Third-party notices
+
+ntt builds on, or is inspired by, the following third-party projects.
+Each entry retains the upstream copyright notice and license text in
+keeping with the relevant license terms.
+
+## Vanadium
+
+ntt's pure-Go ASN.1 frontend (under `internal/asn1/`), its Wadler-style
+TTCN-3 formatter combinator layer, its schema-driven TTCN-3 AST
+generator (under `ttcn3/v2/syntax/nodes/`), and the `Rule` / `Context`
+lifecycle of the new lint engine were inspired by the design of
+[Vanadium](https://github.com/makekryl/vanadium) by Mikhail Krylov.
+
+The directly-attributable architectural concepts include, but are not
+limited to:
+
+- `Asn1ModuleBasket` (Vanadium) -> `resolver.Basket` (ntt)
+- `ClassObjectParser` / `ClassSetResolver` (Vanadium) ->
+  `class.WithSyntaxParser` / `class.ObjectSetResolver` (ntt)
+- `Asn1AstTransformer` (Vanadium) -> `transform.LowerModule` (ntt)
+- `src/ast/nodes.yml` schema-driven AST (Vanadium) ->
+  `ttcn3/v2/syntax/nodes` generator (ntt)
+- `format::PrintDirective` combinator vocabulary (Vanadium) ->
+  Wadler-style document combinator layer in ntt's formatter
+- Lint `Rule` with `Register` / `Check` / `Exit` lifecycle (Vanadium) ->
+  ntt's rule scaffolding
+
+No verbatim Vanadium source code was copied into ntt - the ports above
+are reimplementations in Go - but the design lineage is direct and is
+acknowledged here.
+
+```
+BSD 3-Clause License
+
+Copyright (c) 2025, Mikhail Krylov
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```

docs/getting-started.md

@@ -0,0 +1,152 @@
+# Getting started with ntt
+
+This walkthrough gets you from "I just installed ntt" to running a
+TTCN-3 test and using the LSP features in your editor in under five
+minutes. It assumes you already have ntt on your PATH; see the
+[install instructions](../README.md#install) if you don't.
+
+## 1. Create a test project
+
+Pick a working directory and drop in a single test file. We'll use
+`/tmp/hello-ntt` for this example - swap in any path you like, but make
+sure the path you pick has no spaces in it (a Windows-friendly
+restriction).
+
+```sh
+mkdir -p /tmp/hello-ntt
+cd /tmp/hello-ntt
+```
+
+Create a `package.yml` so ntt recognises this folder as a project root:
+
+```yaml
+# /tmp/hello-ntt/package.yml
+name: hello
+source_dir: .
+```
+
+Create the test file itself:
+
+```ttcn3
+// /tmp/hello-ntt/Hello.ttcn3
+module Hello {
+    function add(integer a, integer b) return integer {
+        return a + b;
+    }
+
+    testcase TC_Add() runs on system {
+        if (add(2, 3) == 5) {
+            setverdict(pass);
+        } else {
+            setverdict(fail);
+        }
+    }
+
+    control {
+        execute(TC_Add());
+    }
+}
+```
+
+## 2. List discovered tests
+
+```sh
+ntt list
+```
+
+You should see:
+
+```
+Hello.TC_Add
+```
+
+If you don't, double-check that you ran `ntt` from inside the project
+directory and that `package.yml` is in the same folder as the `.ttcn3`
+file.
+
+## 3. Run the test
+
+```sh
+ntt run
+```
+
+ntt executes the `control` block, which in turn calls our testcase, and
+reports a pass verdict:
+
+```
+=== RUN   Hello.TC_Add
+=== PASS  Hello.TC_Add  0.001s
+```
+
+If you change `add(2, 3) == 5` to `add(2, 3) == 6` and re-run, you'll
+get a failing verdict and a non-zero exit status - exactly what a CI
+pipeline needs.
+
+## 4. Format the code
+
+```sh
+ntt format Hello.ttcn3
+```
+
+This normalises whitespace and reflows long lines while preserving
+behaviour. Use `--diff` to preview the changes without writing them
+back to disk.
+
+## 5. Lint the project
+
+```sh
+ntt lint
+```
+
+ntt's built-in linter catches common mistakes (missing default cases,
+unused imports, suspicious type coercions). Configure it via the
+`lint:` section of `package.yml`; the defaults are sensible for a quick
+start.
+
+## 6. Hook up your editor
+
+Both [VS Code](https://marketplace.visualstudio.com/items?itemName=Nokia.ttcn3)
+and [vim-lsp-settings](https://github.com/mattn/vim-lsp-settings)
+auto-detect ntt as the TTCN-3 language server. Open the project folder
+and the editor lights up with:
+
+- semantic highlighting and inlay hints
+- diagnostics on save
+- jump to definition (including jumps from TTCN-3 into ASN.1 files)
+- format-on-save via `ntt format`
+- code actions (`source.organizeImports`, lint quick-fixes)
+
+You can also point any LSP-aware editor at the binary by configuring
+it to launch:
+
+```sh
+ntt langserver
+```
+
+## 7. Working with Titan projects
+
+If you already have a `*.tpd` file from
+[Eclipse Titan](https://projects.eclipse.org/projects/tools.titan),
+ntt can read it directly. Run any ntt command from a directory that
+contains a `.tpd` (and no `package.yml`) and ntt will discover the
+descriptor automatically. You can also point at it explicitly:
+
+```sh
+ntt list path/to/myproject.tpd
+```
+
+Referenced sub-projects (`<ReferencedProject>` in the XML) are loaded
+transitively, so the same command works for multi-module Titan
+projects.
+
+
+## 8. Where to go next
+
+- Browse the [ARCHITECTURE.md](../ARCHITECTURE.md) doc to understand
+  how ntt is laid out internally.
+- Run `ntt help` for the full command list - `run`, `list`, `tags`,
+  `show`, `report`, `cover`, and others.
+- Look at `examples/cmake/` for a CMake-driven integration that builds
+  test adapters together with the TTCN-3 code.
+- File feature requests and bug reports on
+  [GitHub issues](https://github.com/nokia/ntt/issues).