plainscript-lang 0.1.7-latest

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.
Files changed (42) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +815 -0
  3. package/compiler/bundler.js +86 -0
  4. package/compiler/cli.js +843 -0
  5. package/compiler/dependency-detector.js +173 -0
  6. package/compiler/formatter.js +170 -0
  7. package/compiler/generator.js +2032 -0
  8. package/compiler/lexer.js +413 -0
  9. package/compiler/parser.js +2077 -0
  10. package/compiler/version.js +6 -0
  11. package/docs/PLINJS_SPEC.md +1051 -0
  12. package/docs/index.html +2287 -0
  13. package/docs/logo.jpg +0 -0
  14. package/docs/website/index.html +1500 -0
  15. package/docs/website/script.js +197 -0
  16. package/docs/website/style.css +1117 -0
  17. package/examples/arrays.pln +13 -0
  18. package/examples/cache-and-jobs.pln +29 -0
  19. package/examples/database.pln +41 -0
  20. package/examples/day2.pln +7 -0
  21. package/examples/day3.pln +11 -0
  22. package/examples/deployment.pln +12 -0
  23. package/examples/email-send.pln +22 -0
  24. package/examples/expressions.pln +40 -0
  25. package/examples/football-backend/app.pln +90 -0
  26. package/examples/hello.pln +3 -0
  27. package/examples/id-verification/app.pln +29 -0
  28. package/examples/id-verification/make-sample-id.js +123 -0
  29. package/examples/loops.pln +17 -0
  30. package/examples/objects.pln +12 -0
  31. package/examples/rest-api-fetch.pln +94 -0
  32. package/examples/rest-api.pln +68 -0
  33. package/examples/scheduled-tasks.pln +23 -0
  34. package/examples/server.pln +25 -0
  35. package/examples/start.pln +2 -0
  36. package/examples/stdlib.pln +41 -0
  37. package/examples/telegram-bot.pln +42 -0
  38. package/examples/web-app.pln +20 -0
  39. package/examples/websocket-server.pln +27 -0
  40. package/examples/whatsapp-bot/pairing.pln +17 -0
  41. package/examples/whatsapp-bot/qr.pln +8 -0
  42. package/package.json +47 -0
@@ -0,0 +1,173 @@
1
+
2
+ // Runtime dependency detection for PlainScript source files.
3
+ //
4
+ // This module only inspects source/AST data. It never installs packages or
5
+ // checks the filesystem, so it can be reused by the CLI, editors, and tools.
6
+
7
+ const { builtinModules } = require('module');
8
+ const { tokenize } = require('./lexer');
9
+ const { parse } = require('./parser');
10
+
11
+ // PlainScript's friendly module names mapped to the npm packages they require.
12
+ const PACKAGE_MAP = Object.freeze({
13
+ express: 'express',
14
+ sqlite: 'better-sqlite3',
15
+ fs: 'fs',
16
+ path: 'path',
17
+ // v2.0.1 — OCR statements are backed by tesseract.js. The mapping keeps the
18
+ // implementation dependency out of PlainScript's language surface: source says
19
+ // `ocr ... as text`, tooling installs tesseract.js.
20
+ ocr: 'tesseract.js',
21
+ // v2.1.0 — PostgreSQL behind the friendly "postgres" name.
22
+ postgres: 'pg',
23
+ // v2.1.0 — backend integrations keep implementation packages out of source.
24
+ mailer: 'nodemailer',
25
+ scheduler: 'croner',
26
+ websocket: 'ws',
27
+ cache: 'redis',
28
+ // v2.1.1 — "accept uploads" is backed by multer; the WebAssembly SQLite
29
+ // engine used by the `database` statement's fallback chain is sql.js.
30
+ uploads: 'multer',
31
+ 'wasm-sqlite': 'sql.js',
32
+ // v2.1.1 — WhatsApp bots run on Baileys; QR codes render in the terminal
33
+ // through qrcode-terminal. Neither package ever appears in PlainScript source.
34
+ whatsapp: '@whiskeysockets/baileys',
35
+ 'wa-qrcode': 'qrcode-terminal',
36
+ });
37
+
38
+ const BUILTIN_MODULES = new Set(builtinModules);
39
+
40
+ function isBuiltinModule(name) {
41
+ return BUILTIN_MODULES.has(name) || BUILTIN_MODULES.has(`node:${name}`);
42
+ }
43
+
44
+ // v2.0.1 — split an npm specifier into its package name and version range.
45
+ //
46
+ // "express" → { name: "express", spec: null }
47
+ // "left-pad@^1.3" → { name: "left-pad", spec: "^1.3" }
48
+ // "@scope/pkg" → { name: "@scope/pkg", spec: null } (scope, not version)
49
+ // "@scope/pkg@2" → { name: "@scope/pkg", spec: "2" }
50
+ //
51
+ // The "@" that starts an npm scope sits at index 0 and never marks a version,
52
+ // so the search for the version separator starts at index 1.
53
+ function splitPackageSpec(specifier) {
54
+ const at = specifier.indexOf('@', 1);
55
+ if (at === -1) return { name: specifier, spec: null };
56
+ return { name: specifier.slice(0, at), spec: specifier.slice(at + 1) };
57
+ }
58
+
59
+ function visit(node, onUse) {
60
+ if (!node || typeof node !== 'object') return;
61
+
62
+ if (Array.isArray(node)) {
63
+ for (const item of node) visit(item, onUse);
64
+ return;
65
+ }
66
+
67
+ if (node.type === 'UseStatement') {
68
+ onUse(node.module);
69
+ } else if (node.type === 'WebAppStatement') {
70
+ // The `web app` shorthand creates an Express application.
71
+ onUse('express');
72
+ } else if (node.type === 'DatabaseStatement') {
73
+ // v2.1.1 — `database` runs SQLite through a portable engine chain:
74
+ // better-sqlite3 (native) first, sql.js (WebAssembly) as the fallback.
75
+ // "using" picks one engine explicitly.
76
+ if (node.driver === 'wasm') {
77
+ onUse('wasm-sqlite');
78
+ } else if (node.driver === 'native') {
79
+ onUse('sqlite');
80
+ } else {
81
+ onUse('sqlite');
82
+ onUse('wasm-sqlite');
83
+ }
84
+ } else if (node.type === 'AcceptUploadsStatement') {
85
+ // v2.1.1 — `accept uploads` is backed by multer under the hood.
86
+ onUse('uploads');
87
+ } else if (node.type === 'PostgresStatement') {
88
+ // v2.1.0 — `postgres "<url>"` uses node-postgres under the hood.
89
+ onUse('postgres');
90
+ } else if (node.type === 'OcrStatement') {
91
+ // v2.0.1 — `ocr "<image>" as <variable>` uses tesseract.js under the hood.
92
+ onUse('ocr');
93
+ } else if (node.type === 'MailTransportStatement' || node.type === 'SendMailStatement') {
94
+ // v2.1.0 — email statements use nodemailer under the hood.
95
+ onUse('mailer');
96
+ } else if (node.type === 'ScheduleStatement') {
97
+ // v2.1.0 — cron schedules use croner under the hood.
98
+ onUse('scheduler');
99
+ } else if (node.type === 'WebSocketServerStatement') {
100
+ // v2.1.0 — websocket servers use ws under the hood.
101
+ onUse('websocket');
102
+ } else if (node.type === 'CacheStatement') {
103
+ // v2.1.0 — cache statements use the redis client under the hood.
104
+ onUse('cache');
105
+ } else if (node.type === 'WhatsAppBotStatement') {
106
+ // v2.1.1 — WhatsApp bots run on Baileys and render QR codes with
107
+ // qrcode-terminal; both are implementation packages, never source.
108
+ onUse('whatsapp');
109
+ onUse('wa-qrcode');
110
+ }
111
+
112
+ for (const value of Object.values(node)) {
113
+ if (value && typeof value === 'object') visit(value, onUse);
114
+ }
115
+ }
116
+
117
+ /**
118
+ * Return the unique npm packages required by PlainScript `use` statements
119
+ * `web app` and `database` shorthand blocks.
120
+ *
121
+ * @param {string|object} source PlainScript source text or a parsed PlainScript AST
122
+ * @returns {string[]} package names in first-seen order
123
+ */
124
+ function detectDependencies(source) {
125
+ const ast = typeof source === 'string'
126
+ ? parse(tokenize(source))
127
+ : source;
128
+ const dependencies = new Set();
129
+
130
+ // Only the resolved npm package decides whether a dependency is real.
131
+ // PlainScript's friendly module names (e.g. sqlite) must not be mistaken for Node
132
+ // built-ins just because Node ships a module with the same name.
133
+ const addPackage = (moduleName) => {
134
+ // A specifier may carry a version range ("left-pad@^1.3.0"); friendly
135
+ // module names resolve through PACKAGE_MAP before the spec is re-attached,
136
+ // so `use sqlite@7` still maps to better-sqlite3@7.
137
+ const { name, spec } = splitPackageSpec(moduleName);
138
+ const packageName = PACKAGE_MAP[name] || name;
139
+ if (!isBuiltinModule(packageName)) {
140
+ dependencies.add(spec ? `${packageName}@${spec}` : packageName);
141
+ }
142
+ };
143
+
144
+ visit(ast, addPackage);
145
+
146
+ // Additional check for the `database "..."` shorthand when the source is a string.
147
+ // This ensures detection even if the parser does not produce a DatabaseStatement node.
148
+ if (typeof source === 'string') {
149
+ // Look for patterns like: database "file.db" or database 'file.db'
150
+ // We use a simple regex to catch the shorthand, honouring an explicit
151
+ // engine choice so the result always matches the AST path above.
152
+ const dbMatch = /database\s+["'][^"']*["'](\s+using\s+["'](\w+)["'])?/.exec(source);
153
+ if (dbMatch) {
154
+ if (dbMatch[2] === 'wasm') {
155
+ addPackage('wasm-sqlite');
156
+ } else if (dbMatch[2] === 'native') {
157
+ addPackage('sqlite');
158
+ } else {
159
+ addPackage('sqlite');
160
+ addPackage('wasm-sqlite');
161
+ }
162
+ }
163
+ }
164
+
165
+ return [...dependencies];
166
+ }
167
+
168
+ module.exports = {
169
+ detectDependencies,
170
+ isBuiltinModule,
171
+ splitPackageSpec,
172
+ PACKAGE_MAP,
173
+ };
@@ -0,0 +1,170 @@
1
+ // Formatter: normalises PlainScript source code style without changing its logic.
2
+ //
3
+ // Rules applied:
4
+ // - Consistent 4-space indentation
5
+ // - Remove trailing whitespace from every line
6
+ // - One blank line between top-level block declarations (make, if, for each, etc.)
7
+ // - Collapse multiple consecutive blank lines into one
8
+ // - Indent multi-line array elements ([...]) relative to their enclosing block
9
+
10
+ const INDENT = ' '; // 4 spaces
11
+
12
+ // Keywords whose line CLOSES a block (printed at depth - 1).
13
+ const DEDENT_WORDS = new Set(['done', 'otherwise', 'recover']);
14
+
15
+ // Patterns whose line OPENS a new block (next line indented).
16
+ const INDENT_STARTERS = [
17
+ /^make\s+\S+\s*\(/, // make name(...)
18
+ /^if\s+/, // if ...
19
+ /^otherwise\b/, // otherwise
20
+ /^for\s+(each|every)\s+/, // for each ... / for every ...
21
+ /^while\s+/, // while ...
22
+ /^when\s+someone\s+visits/, // when someone visits ...
23
+ /^when\s+someone\s+(sends|clicks)\b/, // when someone sends / clicks (Telegram)
24
+ /^when\s+socket\b/, // when socket connects / sends message / disconnects (v2.1)
25
+ /^when\s+nothing\s+matches\b/, // when nothing matches ... done (v2.1.1 404 handler)
26
+ /^javascript\b/, // javascript raw JS block (v1.2)
27
+ /^reply\b.*\bwith\s+buttons\s*$/, // reply ... with buttons ... done (v1.2)
28
+ /^listen\s+on\s+/, // listen on ...
29
+ /^reply\s+json\b/, // reply json
30
+ /^remember\s+\S+\s+as\s*$/, // remember x as (object literal, ends with "as")
31
+ /^remember\s+\S+\s+as\s+javascript\s*$/, // remember x as javascript (raw JS block)
32
+ /^route\s+"/, // route "..." (v0.6 Express DX)
33
+ /^route\s+(get|post|put|patch|delete)\s+"/, // route <method> "..." (v2.1)
34
+ /^group\s+"/, // group "..." (v2.1 route composition)
35
+ /^transaction\s*$/, // transaction (v2.1 atomic DB block)
36
+ /^try\s*$/, // try (v2.1.1 error handling)
37
+ /^recover\b/, // recover [as name] (v2.1.1 error handling)
38
+ /^retry\s+\d+\s+times\b/, // retry N times ... (v2.1.1 retries)
39
+ /^every\s+\d+\s+(seconds?|minutes?|hours?|days?)\b/, // every 5 minutes (v2.1)
40
+ /^schedule\s+"/, // schedule "..." (v2.1 cron)
41
+ /^websocket\s+server\b/, // websocket server (v2.1)
42
+ /^whatsapp\s+bot\s*$/, // whatsapp bot (v2.1.1 WhatsApp runtime)
43
+ /^on\s+message\s*$/, // on message (v2.1.1 WhatsApp handler)
44
+ /^mail\s+transport\s*$/, // mail transport (v2.1)
45
+ /^send\s+mail\s*$/, // send mail (v2.1)
46
+ /^google\s+oauth\s*$/, // google oauth (v2.1.1 Google sign-in)
47
+ /^query\b/, // query SQL block (v0.6 SQLite DX)
48
+ /^insert\b/, // insert SQL block
49
+ /^update\b/, // update SQL block
50
+ /^delete\b(?!\s*["'])/, // delete SQL block (v2.1.1: NOT `delete "<url>"`,
51
+ // which is an HTTP DELETE statement)
52
+ /^execute\b/, // execute SQL block
53
+ ];
54
+
55
+ function opensBlock(line) {
56
+ return INDENT_STARTERS.some(re => re.test(line));
57
+ }
58
+
59
+ // Count occurrences of ch in a line, ignoring characters inside double-quoted
60
+ // strings and after // comments.
61
+ function countUnquoted(line, ch) {
62
+ let count = 0;
63
+ let inString = false;
64
+ for (let i = 0; i < line.length; i++) {
65
+ if (!inString && line[i] === '/' && line[i + 1] === '/') break; // rest is a comment
66
+ if (line[i] === '"' && (i === 0 || line[i - 1] !== '\\')) inString = !inString;
67
+ if (!inString && line[i] === ch) count++;
68
+ }
69
+ return count;
70
+ }
71
+
72
+ // Format a single PlainScript source string and return the formatted version.
73
+ function format(source) {
74
+ const rawLines = source.split('\n');
75
+ const output = [];
76
+ let depth = 0; // keyword block depth (make/if/for each/done …)
77
+ let bracketDepth = 0; // bracket nesting depth for multi-line [ … ]
78
+ let inJsBlock = false; // inside `remember x as javascript … done`
79
+
80
+ for (let i = 0; i < rawLines.length; i++) {
81
+ const original = rawLines[i];
82
+ const stripped = original.replace(/\s+$/, ''); // remove trailing whitespace
83
+ const content = stripped.trim();
84
+
85
+ // ── Inside a raw JavaScript block ───────────────────────────────────────
86
+ // JavaScript must be preserved verbatim: do not re-indent or trim its
87
+ // lines, and do not apply PlainScript bracket/blank-line rules (RFC-0011 §31).
88
+ if (inJsBlock) {
89
+ if (content === 'done') {
90
+ if (depth > 0) depth--;
91
+ output.push(INDENT.repeat(depth) + 'done');
92
+ inJsBlock = false;
93
+ } else {
94
+ output.push(original);
95
+ }
96
+ continue;
97
+ }
98
+
99
+ // Blank lines are preserved outside brackets; suppressed inside them.
100
+ if (content === '') {
101
+ if (bracketDepth === 0) output.push('');
102
+ continue;
103
+ }
104
+
105
+ const opens = countUnquoted(content, '[');
106
+ const closes = countUnquoted(content, ']');
107
+
108
+ // ── Inside a multi-line array [ … ] ──────────────────────────────────────
109
+ if (bracketDepth > 0) {
110
+ // Use the lower bracket depth so a closing ] de-indents before printing.
111
+ const nextBracketDepth = bracketDepth + opens - closes;
112
+ const indentLevel = depth + Math.min(bracketDepth, nextBracketDepth);
113
+ output.push(INDENT.repeat(Math.max(0, indentLevel)) + content);
114
+ bracketDepth = Math.max(0, nextBracketDepth);
115
+ continue;
116
+ }
117
+
118
+ // ── Normal line ───────────────────────────────────────────────────────────
119
+
120
+ const firstWord = content.split(/\s+/)[0];
121
+
122
+ // Dedenting keywords: reduce depth BEFORE printing this line.
123
+ if (DEDENT_WORDS.has(firstWord) && depth > 0) {
124
+ depth--;
125
+ }
126
+
127
+ // Insert exactly one blank line before a top-level block-opening statement
128
+ // (e.g. make, if, for each) when prior content exists.
129
+ // Simple statements like remember/show/becomes are NOT block openers and
130
+ // do NOT get a blank line inserted before them.
131
+ if (depth === 0 && opensBlock(content) && output.length > 0) {
132
+ let lastNonEmpty = output.length - 1;
133
+ while (lastNonEmpty >= 0 && output[lastNonEmpty] === '') lastNonEmpty--;
134
+
135
+ if (lastNonEmpty >= 0 && output[output.length - 1] !== '') {
136
+ output.push('');
137
+ }
138
+ }
139
+
140
+ output.push(INDENT.repeat(depth) + content);
141
+
142
+ // Opening keywords: increase depth AFTER printing this line.
143
+ if (opensBlock(content)) {
144
+ if (/^remember\s+\S+\s+as\s+javascript\s*$/.test(content) ||
145
+ /^javascript\s*$/.test(content)) inJsBlock = true;
146
+ depth++;
147
+ }
148
+
149
+ // Update bracket depth for multi-line arrays starting on this line.
150
+ bracketDepth = Math.max(0, bracketDepth + opens - closes);
151
+ }
152
+
153
+ // Collapse consecutive blank lines into one.
154
+ const collapsed = [];
155
+ let prevBlank = false;
156
+ for (const line of output) {
157
+ const blank = line === '';
158
+ if (blank && prevBlank) continue;
159
+ collapsed.push(line);
160
+ prevBlank = blank;
161
+ }
162
+
163
+ // Strip leading and trailing blank lines, then add a single trailing newline.
164
+ while (collapsed.length > 0 && collapsed[0] === '') collapsed.shift();
165
+ while (collapsed.length > 0 && collapsed[collapsed.length - 1] === '') collapsed.pop();
166
+
167
+ return collapsed.join('\n') + '\n';
168
+ }
169
+
170
+ module.exports = { format };