Protos VS Code Extension

VS Code extension for the Protos programming language.

This repository is the product and distribution home for the Protos VS Code extension. The canonical Protos language, specification, parser, resolver and runtime remain owned by the guillermomolina/protos repository.

Protos runtime authority

This repository consumes an official published Protos runtime for real Run/Debug acceptance. It does not build Protos from source as part of the extension pipeline.

The exact published runtime identity is recorded in protos-source.lock.json:

repository      = guillermomolina/protos
source revision = b20271369d00f8937890a4a94048bb1754b688b8
release tag     = v0.3.442
release asset   = protos-0.3.442-native-linux-x86_64.zip
asset sha256    = e3aea0bc715a0351cf09d5fe3a52471d444ab17b80924cc7630bf96f2a289380
graalvm release = 25.4.4.1.1

For acceptance, the lock is the authority for both the exact Protos source identity and the immutable published Native artifact that carries it.

scripts/install_locked_protos_runtime.py downloads that asset from the official GitHub Release, verifies its SHA-256, verifies SOURCE.txt and RUNTIME.txt, and exposes its bin/protos launcher to the packaged extension acceptance tests.

The extension must remain a thin editor integration. It must not become a second implementation of the Protos language or runtime.

In particular, this repository does not own:

• Protos grammar or language semantics;
• parsing or semantic analysis;
• name resolution;
• runtime implementation;
• Java/GraalVM implementation details;
• Protos launcher internals.

Those responsibilities remain in the canonical Protos repository.

Extension identity

extension id:    guillermomolina.protos
extension name:  protos
publisher:       guillermomolina
extension ver.:  0.2.4
engines.vscode:  ^1.104.0
language id:     protos
file extension:  .protos
TextMate scope:  source.protos

The extension uses the external Protos launcher configured through:

protos.runtime.executable

The default value is:

protos

The extension does not embed the Protos runtime.

Features

The current extension provides the following integration surfaces:

• Protos language identification for .protos files;
• non-normative TextMate syntax highlighting;
• language configuration for comments and structural delimiters;
• Protos: Run Current File;
• Protos debugging through VS Code's Debug Adapter Protocol integration;
• Protos language-server client integration;
• whole-document formatting through the standard LSP textDocument/formatting path, with canonical formatting owned by the configured Protos runtime;
• local and VS Code Remote workspace support where the corresponding Protos launcher is available in the workspace extension host.

The extension intentionally keeps these responsibilities at the editor boundary. Language semantics remain external to the extension.

Local development

Install the exact dependency set recorded in the lockfile:

npm ci

Run the complete repository test authority:

make test

make test runs the historical repository baseline through npm test, then runs the installed-VSIX acceptance through npm run test:acceptance. The acceptance path packages and canonicalizes the VSIX, installs the locked published Protos runtime, installs the actual VSIX into pinned VS Code 1.140.0, and validates clean installation, real Run, real Debug, the existing deterministic formatting-protocol scenario, and real released-runtime Format Document / format-on-save behaviour.

Build the production extension bundle:

npm run build

Generate or validate the committed packaging assets:

npm run package:assets

Run the structural validators:

python3 test/validate_grammar.py
python3 test/validate_extension.py
python3 test/validate_packaging.py
python3 test/validate_vsix.py
python3 test/validate_reproducibility.py

Run the Node.js integration tests:

node test/run_current_file.test.js
node test/debug_integration.test.js
node test/language_server_integration.test.js

The extension can also be loaded directly into an Extension Development Host:

npm ci
npm run build
code --new-window --extensionDevelopmentPath="$PWD"

A real Protos launcher must be available through PATH or through the protos.runtime.executable setting.

Packaging

The production VSIX is built with the pinned @vscode/vsce packaging tool.

The normal packaging flow is:

npm ci
npm run vscode:prepublish
npm run package:vsix -- --out /tmp/protos.vsix
python3 test/validate_vsix.py /tmp/protos.vsix

The production package contains only the approved extension surface.

Development-only material such as source-only JavaScript, tests, fixtures, packaging scripts, the npm lockfile, generated metadata and raw node_modules content must not be shipped inside the VSIX.

The package boundary is enforced by .vscodeignore and the packaging validators.

Deterministic VSIX artifacts

The CI pipeline canonicalizes the VSIX after packaging.

The canonicalization performed by scripts/canonicalize_vsix.js fixes the artifact properties that are otherwise dependent on the local packaging environment, including:

ZIP member ordering      = lexicographic
ZIP compression           = STORE
ZIP member permissions    = fixed
ZIP timestamps            = derived from Git source revision
semantic member bytes    = unchanged

The resulting VSIX is therefore reproducible from the same extension source revision and dependency lock.

The CI pipeline also records the SHA-256 digest of the canonical VSIX.

Package assets and notices

The production bundle includes the JavaScript dependencies required by the extension.

The corresponding third-party licensing information is maintained in:

THIRD_PARTY_NOTICES.txt

The file is generated deterministically from the installed dependency set and the production bundle metadata. It must not be edited manually.

The package also contains:

license.txt

which is the license file required inside the VSIX.

The repository-level license is:

LICENSE.TXT

Both the repository and distributed VSIX must preserve the applicable APL-1.0 licensing terms and required third-party notices.

Continuous integration

GitHub Actions use the same repository test authority as local development. The workflow builds the committed devcontainer and executes exactly:

make test

The workflow does not maintain separate implementations of packaging, clean-install, Run, or Debug acceptance.

The authority is layered as:

make test
    │
    ├── npm test
    │     repository baseline
    │
    └── npm run test:acceptance
          │
          ├── package + validate canonical VSIX
          ├── install exact published Protos Native runtime
          ├── clean installed-extension acceptance
          ├── real Run acceptance
          ├── real Debug acceptance
          ├── deterministic formatting-protocol acceptance
          └── real released-runtime formatting acceptance

The acceptance path consumes the exact published Protos Native runtime from protos-source.lock.json; it does not checkout or compile Protos and does not install a separate Java/GraalVM runtime.

The same acceptance run produces protos-vscode.vsix and protos-vscode.vsix.sha256. After make test succeeds, GitHub Actions uploads those files as the canonical workflow artifact. CI therefore validates and publishes the artifact produced by the same repository authority instead of rebuilding a second VSIX in downstream jobs.

Reproducibility

A successful CI run must establish all of the following:

exact published Protos runtime
        +
exact Protos source identity carried by that runtime
        +
exact npm dependency lock
        +
deterministic package assets
        +
deterministic VSIX canonicalization
        =
reproducible VSIX artifact + reproducible acceptance runtime

Changing the pinned Protos release/runtime identity, extension source, dependency lock, packaging inputs or package assets must therefore produce a corresponding artifact or acceptance change, or an explicit reviewable reason why the semantic result remains unchanged.

Issue tracking

This repository has independent issue tracking from guillermomolina/protos.

Issues concerning the VS Code extension belong here, including:

• VS Code editor integration;
• language-server client behavior;
• debugger and DAP integration;
• Run Current File;
• VS Code Remote integration;
• extension packaging and VSIX reproducibility;
• Marketplace/release concerns;
• extension-specific CI and distribution failures.

Issues concerning the Protos language, runtime, compiler, standard library or other core implementation remain in the canonical Protos repository.

Historical work that originally produced the extension may reference project milestones such as LM009, but those historical identifiers do not make the Protos repository the owner of current extension work.

Repository boundary

The repository boundary is intentionally:

guillermomolina/protos
    canonical language/runtime source
                │
                │ published release artifact
                ▼
guillermomolina/protos-vscode-extension
    editor integration
    packaging
    CI
    VSIX artifacts
    distribution

The dependency therefore flows through the official Protos distribution boundary rather than through a second source build in the editor repository.

The extension repository must not copy or fork the Protos runtime merely to make the editor pipeline self-contained.

License

Protos and this extension are distributed under the Adaptive Public License 1.0.

The complete license text is included in LICENSE.TXT and the VSIX-compatible copy is provided as license.txt.

Third-party dependency notices are included in THIRD_PARTY_NOTICES.txt.