plainscript-lang 1.1.0 → 1.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,7 +4,7 @@ This document is the single source of truth for the PlainScript language
4
4
  surface. Compiler behavior (`compiler/lexer.js`, `compiler/parser.js`,
5
5
  `compiler/generator.js`) overrides any prose in this or other docs.
6
6
 
7
- Version: 1.0.363
7
+ Version: 1.1.5
8
8
 
9
9
  ---
10
10
 
@@ -62,6 +62,14 @@ Line 1, Column 10: Expected a variable name after "remember".
62
62
  Pick a different name (see docs/PLAINSCRIPT-GRAMMAR.md).
63
63
  ```
64
64
 
65
+ Reserved words may be used deliberately by enclosing the word in backticks. The
66
+ escaped form is an identifier, not a template string:
67
+
68
+ ```plainscript
69
+ remember `now` as 1
70
+ show `now`
71
+ ```
72
+
65
73
  ### Operators
66
74
 
67
75
  | Token | Meaning |
@@ -74,6 +82,11 @@ Pick a different name (see docs/PLAINSCRIPT-GRAMMAR.md).
74
82
  | `...` | spread |
75
83
  | `(` `)` `[` `]` `{` `}` `,` `:` | grouping, literals, comma, object colon |
76
84
 
85
+ Natural-language comparisons normalize to the same binary operators. Supported
86
+ forms include `is greater than` / `is more than` (`>`), `is less than` / `is
87
+ fewer than` (`<`), `is greater than or equal to` / `is more than or equal to`
88
+ (`>=`), `is less than or equal to` (`<=`), and `is at least` / `is at most`.
89
+
77
90
  ### Assignment operators
78
91
 
79
92
  | Operator | Meaning |
@@ -216,8 +229,33 @@ done
216
229
 
217
230
  The generated function validates `user` before entering its body. The static
218
231
  checker also validates literal arguments, typed bindings, return contracts,
219
- collection elements, nested fields, and known member access. It remains
220
- conservative for expressions whose types are unknown.
232
+ collection elements, nested fields, and known member access. Since v1.1.5,
233
+ canonical standard-library calls and common text/list methods propagate their
234
+ known return types through expressions, for example
235
+ `"Ada".toLowerCase().includes("a")` is known to be boolean and
236
+ `"a,b".split(",")` is known to be a list of text. Typed `set of T`, `map of K to V`, and fixed-size `tuple of A, B` contracts are checked recursively. It remains conservative for
237
+ unknown JavaScript/npm calls and treats them as `any`.
238
+
239
+ ### Async values and Promise contracts
240
+
241
+ Calls to asynchronous functions are tracked as `Promise of T` values. A
242
+ function body containing `wait for` is therefore asynchronous even when its
243
+ resolved return contract is written as `returns text`. Use `wait for` when a
244
+ resolved value is required:
245
+
246
+ ```plainscript
247
+ make verify() returns text
248
+ wait for sleep(10)
249
+ give "verified"
250
+ done
251
+
252
+ remember result as wait for verify()
253
+ ```
254
+
255
+ The checker reports `PLN-ASYNC-MISSING-AWAIT` when a Promise is assigned,
256
+ passed to a typed synchronous parameter, or returned where a resolved value is
257
+ required. Explicit raw contracts may use `returns Promise of text`; the body
258
+ is still checked against the resolved `text` value.
221
259
 
222
260
  ## 5. Statements and blocks
223
261
 
@@ -237,18 +275,73 @@ equivalent; `end` maps to the same terminator as `done` in the lexer.
237
275
  | `switch <value> against` | `->` cases | `done` |
238
276
  | `try` | body with `recover as <err>` / `finally` clauses | `done` |
239
277
  | `web app` / `route <method> "<path>"` / `when someone visits "<path>"` / `listen on <port>` blocks | body | `done` |
240
- | `database "file.db"` SQL blocks (`query`, `insert`, `update`, `delete`, `execute`) | raw SQL | `done` (or `end`) |
278
+ | `database "file.db"` SQL blocks (`query`, `insert`, `update`, `delete`, `execute`) | raw SQL with `{name}` bound parameters | `done` (or `end`) |
241
279
  | `run in parallel` | concurrent statements (each statement's value is awaited and resolved with `Promise.all`, collected in body order) | `done as <name>` |
242
280
  | `when "<event>" happens` | body | `done` |
243
281
  | `every <interval>` / `schedule "<cron>"` | body | `done` |
244
282
  | `websocket server`, `bot`, `whatsapp bot`, `mail transport` | body | `done` |
245
283
  | `stream "<file>" as <line>` | body | `done` |
246
- | `test "<name>"` | `check` / `equals` / `raises` | `done` |
284
+ | `test "<name>"` | `check` / `equals` / `raises` / `has field` | `done` |
247
285
 
248
286
  A `make` body that contains `yield` compiles to a generator function
249
- (`function*`). SQL block text is passed through verbatim to SQLite.
287
+ (`function*`). SQL block text is passed through to the selected database driver,
288
+ except for safe PlainScript parameter placeholders.
289
+
290
+ Native tests can assert the shape of JSON-like records with
291
+ `check data of response has field "status"`. The assertion checks for an own
292
+ property and fails when the value is null or the field is absent.
293
+
294
+ ### SQL interpolation
295
+
296
+ SQL placeholders use a PlainScript value expression inside braces. The compiler
297
+ replaces `{name}` or `{imageHash(image)}` with a driver parameter marker and
298
+ passes the resulting value separately to the prepared statement; values are
299
+ never concatenated into SQL text.
300
+
301
+ ```plainscript
302
+ remember email as request.body.email
303
+ remember rows as query
304
+ SELECT receipt_id FROM receipts WHERE email = {email}
305
+ done
306
+ ```
307
+
308
+ Expressions are parsed as PlainScript before compilation. Malformed or raw
309
+ statement text is rejected at compile time; for example, this is invalid:
310
+
311
+ ```text
312
+ {imageHash(image); DROP TABLE receipts}
313
+ ```
314
+
315
+ For complex expressions, binding first is still recommended because it makes
316
+ the source and inferred value easier to read:
317
+
318
+ ```plainscript
319
+ remember receiptHash as imageHash(image)
320
+ remember rows as query
321
+ SELECT receipt_id FROM receipts WHERE hash = {receiptHash}
322
+ done
323
+ ```
324
+
325
+ The same binding rule applies to `query`, `insert`, `update`, `delete`, and
326
+ `execute`. SQL injection attempts supplied as values remain data because the
327
+ prepared statement receives them as parameters.
328
+
329
+ ## 6. Module and npm imports
330
+
331
+ Selective imports may rename an exported symbol with `as`:
332
+
333
+ ```plainscript
334
+ import { createHash as hash, randomUUID } from "crypto"
335
+ ```
336
+
337
+ For npm packages, the compiler emits a CommonJS `require` and destructures the
338
+ requested exports. The example creates local bindings named `hash` and
339
+ `randomUUID`, while the package exports remain `createHash` and `randomUUID`.
340
+ The same syntax works for local `.pln` modules; the bundler creates the alias
341
+ after resolving the dependency. A plain `import { name } from ...` keeps the
342
+ exported name unchanged.
250
343
 
251
- ## 6. Expressions
344
+ ## 7. Expressions
252
345
 
253
346
  Recursive-descent parsing with precedence. Member access uses `of`:
254
347
 
@@ -0,0 +1,79 @@
1
+ # PlainScript v1.1.5 Completeness Gap Analysis and Implementation Plan
2
+
3
+ ## Correct milestone thesis
4
+
5
+ PlainScript **v1.1.5 is the completeness milestone**. It is not merely a trustworthiness foundation with mainstream language capability deferred to v1.2.x. The release must contain the general-purpose capabilities needed to build serious multi-file software without requiring a new domain-specific compiler feature for every application category.
6
+
7
+ > PlainScript should provide powerful general-purpose language primitives, a broad standard library, and strong JavaScript/npm interoperability. Web backends, APIs, CLIs, bots, games, automation, libraries, and database applications should be built from those primitives rather than from an ever-growing collection of one-off syntax features.
8
+
9
+ The current `main` branch is a verified trustworthiness slice, not the finished completeness release. This document is the active contract for the remaining work.
10
+
11
+ ## Already implemented and retained
12
+
13
+ - Near-English declarations, functions, lambdas, records, collections, templates, control flow, errors, async syntax, modules, npm imports, CLI compilation, source maps, and an in-process LSP.
14
+ - Recursive contracts for named records, optional fields, unions, lists, dictionaries, typed returns, Promise tracking, indexes, assignments, and common expression results.
15
+ - Local dependency discovery, aliases, directory resolution, cycle diagnostics, named/aliased/namespace imports, barrel exports, SQLite/WASM, HTTP, filesystem, crypto, CLI, browser, Canvas/WebGL, WebSocket, bots, uploads, sessions, and broad runtime helpers.
16
+ - Verified regressions for collection soundness, destructuring, module export visibility, incremental LSP edits, retry failure propagation, release metadata, and the complete existing test suite.
17
+
18
+ ## Remaining completeness gaps
19
+
20
+ ### Language and type system
21
+
22
+ - Generic or otherwise expressive reusable types, including substitution and useful diagnostics.
23
+ - Named aliases and normalized recursive unions.
24
+ - Discriminated unions with flow-sensitive narrowing.
25
+ - Structural patterns with bindings, guards, alternatives, impossible-arm diagnostics, and useful exhaustiveness checking.
26
+ - A capable object/abstraction model: validated constructors, typed members/methods, predictable record/kind behavior, and interoperable class/object semantics.
27
+ - Typed tuple, Set, and Map contracts plus mutation checking and generic collection operations.
28
+
29
+ ### Runtime and standard library
30
+
31
+ - Portable JSON/value conversion for Map, Set, BigInt, undefined, circular values, and deterministic encoding. **Implemented in this milestone.**
32
+ - Correct calendar/timezone/UTC date semantics and complete formatting.
33
+ - Async/atomic filesystem operations, directory streams, and teaching errors.
34
+ - Cancellable and streaming subprocesses with cwd/env/timeout/signal/stdio options.
35
+ - Richer HTTP request/response/options/abort/retry/stream support.
36
+ - Precise browser/package target behavior and a truthful WebGPU/Three.js interoperability contract.
37
+
38
+ ### Async, errors, and resources
39
+
40
+ - Promise.any semantics, aggregate failures, loser/sibling cleanup, and structured task handles.
41
+ - Cancellation tokens/signals and timeout propagation for supported operations.
42
+ - Retry predicates, backoff/deadlines, normalized error causes, and source context.
43
+ - Background/scheduled task observation and shutdown ownership.
44
+ - Scope-based `defer`/`using`-style cleanup for streams, subprocesses, databases, caches, sockets, and schedules.
45
+
46
+ ### Modules and interoperability
47
+
48
+ - A real module linker with canonical module IDs, private scopes, isolated declarations, explicit exports, stable aliases, and collision diagnostics.
49
+ - Graph-aware build/check/type analysis rather than flattened synthetic AST checking.
50
+ - Config-driven `rootDir`/`baseUrl`/`paths` resolution and manifest/lockfile reconciliation.
51
+ - Robust CommonJS/ESM/default/named/subpath/exports-condition handling and explicit Node/browser targets.
52
+
53
+ ### Tooling and proof
54
+
55
+ - A real VS Code LSP client, semantic cross-file navigation, structured diagnostics, formatting integration, lifecycle/version/cancellation handling, and stable JSON output.
56
+ - Correct formatter behavior and source-map offsets through generated wrappers and bundled modules.
57
+ - Mandatory CI, packaged-consumer tests, recursive version validation, template/application matrices, real-browser proof, and clearly labelled service-backed or offline integration tests.
58
+
59
+ ## Implementation sequence
60
+
61
+ 1. **Shared semantic spine and module linker:** canonical graph/module IDs, per-module symbols and exports, config-rooted resolution, isolated generated module records, graph-wide diagnostics and type checking.
62
+ 2. **Expressive types and structural control flow:** aliases, closed unions, explicit generic parameters/instantiation, structural patterns, guards, narrowing, impossible/duplicate/unreachable arms, and exhaustiveness.
63
+ 3. **Object and collection completeness:** validated object abstractions, typed methods/members, tuple/Set/Map contracts, and mutation checking.
64
+ 4. **Runtime and error contract:** normalized diagnostics/errors, JSON/date/files/process/HTTP correctness, and compatibility-preserving richer options.
65
+ 5. **Structured async/resource semantics:** Promise.any, task handles, cancellation, timeout propagation, retries/backoff, structured background work, and disposal.
66
+ 6. **Production tooling:** compiler-backed symbols, cross-file LSP, VS Code client, formatter modes, stable diagnostics, and source-map correctness.
67
+ 7. **Executable proof and packaging:** CI, npm tarball consumer, application/template matrices, browser and service contract gates, and release integrity.
68
+
69
+ ## Release gates
70
+
71
+ - `npm test`, docs checks, release checks, formatter checks, LSP/extension smoke, source-map tests, and all type/module/runtime regressions pass in CI.
72
+ - The exact npm tarball installs into a clean consumer and builds/runs a typed multi-file application with isolated modules and source-mapped failures.
73
+ - Generic types/aliases, structural matching/narrowing/exhaustiveness, object abstractions, typed collections, Promise.any/cancellation/disposal, and JS/npm interop each have positive and negative tests.
74
+ - Every advertised example/template is either executable in a deterministic matrix or explicitly annotated with its external-service requirements; compile-only proof is not presented as runtime proof.
75
+ - Versions agree across root/lockfile/compiler/grammar/changelog/LSP/VS Code/templates, and publish uses the immutable artifact that passed the gates.
76
+
77
+ ## Compatibility rule
78
+
79
+ Preserve valid v1.0.363 and v1.1.x programs wherever practical. New completeness features should use unambiguous syntax and explicit diagnostics. Legacy untyped code remains permissive at dynamic boundaries, while new typed code must not silently escape through `any`.
package/package.json CHANGED
@@ -1,15 +1,28 @@
1
1
  {
2
2
  "name": "plainscript-lang",
3
- "version": "1.1.0",
3
+ "version": "1.1.5",
4
4
  "description": "PlainScript - an Intent-Oriented Programming Language. When even a simple sentence can be code.",
5
+ "author": {
6
+ "name": "Ayodele Ayokunle David",
7
+ "email": "davidayodele847@gmail.com"
8
+ },
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "https://github.com/ayoistooslick/plainscript.git"
12
+ },
13
+ "homepage": "https://github.com/ayoistooslick/plainscript#readme",
14
+ "bugs": {
15
+ "url": "https://github.com/ayoistooslick/plainscript/issues"
16
+ },
5
17
  "main": "compiler/cli.js",
6
18
  "bin": {
7
19
  "plainscript": "./compiler/cli.js",
8
20
  "plainscript-lsp": "./compiler/lsp.js"
9
21
  },
10
22
  "scripts": {
11
- "test": "node tests/compiler.test.js && node tests/build.test.js && node tests/telegram.test.js && node tests/ocr.test.js && node tests/nesting.test.js && node tests/backend.test.js && node tests/runtime.test.js && node tests/browser.test.js && node tests/acceptance.test.js && node tests/whatsapp.test.js && node tests/audit.test.js && node tests/sourcemap.test.js && node tests/modules.test.js && node tests/repeat.test.js && node tests/datastructures.test.js && node tests/kernel.test.js && node tests/assignment.test.js && node tests/primitives.test.js && node tests/concurrency.test.js && node tests/terminal.test.js && node tests/cli.test.js && node tests/docs.test.js && node tests/types.test.js && node tests/ir.test.js && node tests/lsp.test.js && node tests/parser-robustness.test.js && node tests/compat/browser-interop.test.js && node tests/compat/language.test.js && node tests/compat/node.test.js && node tests/compat/binary.test.js && node tests/compat/errors.test.js && node tests/compat/async.test.js && node tests/compat/modules.test.js && node tests/compat/npm.test.js && node tests/compat/web.test.js && node tests/compat/real-world.test.js && node tests/torture.test.js && node tests/packaging.test.js && node tools/verify-all-docs.js",
12
- "docs:check": "node tools/verify-all-docs.js"
23
+ "test": "node tests/compiler.test.js && node tests/build.test.js && node tests/telegram.test.js && node tests/ocr.test.js && node tests/nesting.test.js && node tests/backend.test.js && node tests/runtime.test.js && node tests/browser.test.js && node tests/acceptance.test.js && node tests/whatsapp.test.js && node tests/audit.test.js && node tests/sourcemap.test.js && node tests/modules.test.js && node tests/repeat.test.js && node tests/datastructures.test.js && node tests/kernel.test.js && node tests/assignment.test.js && node tests/primitives.test.js && node tests/concurrency.test.js && node tests/formatter.test.js && node tests/terminal.test.js && node tests/cli.test.js && node tests/docs.test.js && node tests/types.test.js && node tests/ir.test.js && node tests/json.test.js && node tests/completeness.test.js && node tests/lsp.test.js && node tests/parser-robustness.test.js && node tests/compat/browser-interop.test.js && node tests/compat/language.test.js && node tests/compat/node.test.js && node tests/compat/binary.test.js && node tests/compat/errors.test.js && node tests/compat/async.test.js && node tests/compat/modules.test.js && node tests/compat/npm.test.js && node tests/compat/web.test.js && node tests/compat/real-world.test.js && node tests/torture.test.js && node tests/packaging.test.js && node tools/verify-all-docs.js",
24
+ "docs:check": "node tools/verify-all-docs.js",
25
+ "release:check": "node tools/check-release-version.js"
13
26
  },
14
27
  "files": [
15
28
  "compiler",