Skip to content

VS Code Extension

Sceleratis edited this page Oct 20, 2026 · 1 revision

VS Code extension

The PlainLogic extension provides syntax highlighting and local structural language features for .plog files. The agent skill interprets and implements the logic separately. Saving a file in VS Code does not compile or convert it.

These instructions describe version 0.3.0, extension ID plainlogic-local.plainlogic, and language ID plainlogic. The manifest supports VS Code 1.85 or later within the 1.x series. Manifest

Build and install from the repository

Install Node.js 22 or later, npm, and VS Code. In a terminal:

git clone https://github.com/Sceleratis/PlainLogic-Language.git
cd PlainLogic-Language
npm ci --ignore-scripts
npm run package

The package command creates dist/plainlogic-0.3.0.vsix. In VS Code, open Extensions, choose … → Install from VSIX, and select that file. If the code command is on your PATH, you can instead run:

code --install-extension dist/plainlogic-0.3.0.vsix

VSIX is VS Code's installable extension format; see its packaging instructions. This repository provides a local package workflow; these instructions do not assume a published Visual Studio Marketplace listing. Node and the development dependencies are used to build the package. The installed extension needs no Python interpreter, separate language server, or AI account. Build and runtime details

Open or create a .plog file. If necessary, choose PlainLogic from VS Code's language mode selector. The default editor configuration uses four spaces, disables indentation detection, and enables quick suggestions outside comments and strings.

Commands and settings

Open the Command Palette and run:

Command Result
PlainLogic: New Draft (plainlogic.newDocument) Opens an untitled document populated from the canonical draft snippet, with editable fields and an unresolved question.
PlainLogic: Open Language Reference (plainlogic.showReference) Opens the extension's bundled Markdown language reference.

Live structural diagnostics are enabled by default. Disable them in Settings or settings.json:

{
    "plainlogic.diagnostics.enabled": false
}

Language features

Feature Implemented behavior
Highlighting Canonical declarations, informal return-first signatures, English steps, exact logic, aliases, inclusive counted loops, and protected native blocks. Colors depend on your theme.
Completion Declared and local names, common types, primitives, and keywords. After covers, bind, or ask, suggestions are filtered to requirement, reference, or question IDs.
Hover Declaration signatures, nearby comment descriptions, and keyword explanations. Hover over a prose line's > marker for English-step guidance.
Outline and folding Named declarations and indented logic/prose blocks, including alias bodies and native regions.
Definition, references, and highlights Unambiguously indexed identifiers in the current document.
Rename Supported declarations and indexed exact-logic uses in the current document, subject to the limits below.
Signature help Direct, unambiguous calls to declared functions, ports, and records; triggered by ( and ,.
File links Relative, forward-slash paths in top-level ref declarations. A #Symbol suffix is a lookup hint; the link opens the file.
Diagnostics Local structure and declared links, including canonical metadata, coverage/readiness conditions, alias issues, and native block margins.

For example, this informal editor fragment enables local navigation; it is not a complete canonical-checker document:

ref helper "src/helper.lua#sendRequest"

fn double(value: Int) -> Int:
    return value * 2

case example:
    expect double(3) == 6

The reference path resolves relative to the saved .plog file's directory, or the first workspace folder for an untitled document. The extension does not check that the file or symbol exists. Absolute paths, backslash paths, URLs, and action URIs do not become links through this provider. Function navigation in this example stays inside this document. Provider implementation · Link and call helpers

Snippets

Type a prefix in a PlainLogic document and choose the matching snippet. Editable placeholders let you fill in names, types, and behavior.

Prefix Inserts
plog Canonical 0.3 draft document
fn, function Canonical or informal function
step, block English step or nested English block
require, open, ask, ref Requirement, unresolved decision, decision use, or source locator
port, case Operation contract or reviewable scenario
if, for, countedfor Conditional, collection loop, or inclusive counted loop
alias, aliasblock Behavior alias declaration or invocation
native, target Literal target-code block or target/runtime context

See the exact snippet definitions.

Boundaries to keep in mind

Editor analysis is lexical and document-local. It does not infer types, resolve APIs across files, execute scenarios, interpret English, check native target syntax, or prove feasibility. A canonical plainlogic 0.1, 0.2, or 0.3 header enables document metadata/readiness checks; informal fragments do not receive missing-header errors. The live checks cover a structural subset of the language. Analyzer

English steps, alias descriptions, comments, strings, and native bodies remain outside code navigation and rename. Native content is displayed as protected literal text rather than delegated to a target-language editor. Field and parameter rename is refused because member uses and named arguments are not resolved. Duplicate or shadowed declarations may prevent navigation. Rename requires a nonreserved ASCII identifier and rejects names already declared in the document. Alias-body scopes are isolated conservatively, so captured outer names are not inferred.

Use validation before implementation, and review prose/native references yourself after a rename. Provider behavior is exercised by VS Code integration checks. For extension development and packaging checks, see Development and Packaging.

Clone this wiki locally