plainscript-lang 1.0.2 → 1.0.3

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 (74) hide show
  1. package/README.md +173 -738
  2. package/compiler/bundler.js +83 -12
  3. package/compiler/cli.js +74 -27
  4. package/compiler/dependency-detector.js +11 -0
  5. package/compiler/generator.js +372 -35
  6. package/compiler/lexer.js +2 -0
  7. package/compiler/parser.js +410 -28
  8. package/compiler/sourcemap.js +142 -0
  9. package/compiler/version.js +1 -1
  10. package/docs/CAPABILITY_GAP_AUDIT.md +98 -534
  11. package/docs/PLAINSCRIPT-SPEC.md +304 -551
  12. package/docs/index.html +127 -598
  13. package/docs/website/script.js +185 -1006
  14. package/docs/website/style.css +220 -656
  15. package/examples/ai-providers.pln +7 -0
  16. package/examples/arrays.pln +4 -12
  17. package/examples/async-errors.pln +18 -0
  18. package/examples/auth-api.pln +3 -50
  19. package/examples/auth-sessions.pln +32 -0
  20. package/examples/basics.pln +14 -0
  21. package/examples/bots.pln +13 -0
  22. package/examples/cache-and-jobs.pln +6 -28
  23. package/examples/cache-schedule.pln +22 -0
  24. package/examples/collections.pln +15 -0
  25. package/examples/concurrency.pln +12 -43
  26. package/examples/conditions.pln +22 -0
  27. package/examples/database.pln +6 -39
  28. package/examples/day2.pln +6 -6
  29. package/examples/day3.pln +4 -10
  30. package/examples/deployment.pln +3 -9
  31. package/examples/email-send.pln +3 -22
  32. package/examples/error-handling.pln +6 -54
  33. package/examples/expressions.pln +7 -40
  34. package/examples/file-uploads.pln +5 -34
  35. package/examples/files-and-config.pln +5 -46
  36. package/examples/files.pln +12 -0
  37. package/examples/football-backend/app.pln +21 -20
  38. package/examples/functions.pln +17 -0
  39. package/examples/hello.pln +2 -3
  40. package/examples/http-client.pln +3 -44
  41. package/examples/http.pln +11 -0
  42. package/examples/id-verification/app.pln +4 -3
  43. package/examples/id-verification/make-sample-id.js +29 -42
  44. package/examples/json.pln +11 -0
  45. package/examples/loops.pln +13 -11
  46. package/examples/modules/app.pln +3 -16
  47. package/examples/modules/main.pln +4 -0
  48. package/examples/modules/math.pln +5 -16
  49. package/examples/mongo.pln +33 -0
  50. package/examples/objects.pln +3 -11
  51. package/examples/ocr.pln +22 -0
  52. package/examples/packages.pln +6 -0
  53. package/examples/record-kinds.pln +6 -42
  54. package/examples/records.pln +15 -0
  55. package/examples/rest-api-fetch.pln +6 -90
  56. package/examples/rest-api.pln +5 -65
  57. package/examples/scheduled-tasks.pln +4 -23
  58. package/examples/search-and-filter.pln +4 -34
  59. package/examples/server.pln +5 -24
  60. package/examples/sessions-and-cookies.pln +4 -50
  61. package/examples/sqlite.pln +23 -0
  62. package/examples/start.pln +2 -2
  63. package/examples/stdlib.pln +4 -41
  64. package/examples/string-verbs.pln +16 -0
  65. package/examples/telegram-ai-bot.pln +19 -0
  66. package/examples/telegram-bot.pln +4 -40
  67. package/examples/testing.pln +13 -0
  68. package/examples/web-api.pln +27 -0
  69. package/examples/web-app.pln +4 -16
  70. package/examples/websocket-server.pln +5 -26
  71. package/examples/websocket.pln +13 -0
  72. package/examples/whatsapp-bot/pairing.pln +4 -5
  73. package/examples/whatsapp-bot/qr.pln +7 -3
  74. package/package.json +3 -2
@@ -7,11 +7,55 @@ const { tokenize } = require('./lexer');
7
7
  const { parse } = require('./parser');
8
8
  const { generate, createGenerationContext, wrapAsync } = require('./generator');
9
9
 
10
- // Returns the import paths declared at the top level of an AST.
10
+ function isLocalImportPath(p) {
11
+ if (!p) return false;
12
+ return p.startsWith('.') || p.startsWith('/') || p.startsWith('\\') || p.startsWith('@/') || p.endsWith('.pln');
13
+ }
14
+
15
+ function resolveImportPath(dir, importPath) {
16
+ let base;
17
+ if (importPath.startsWith('@/')) {
18
+ const srcDir = fs.existsSync(path.resolve(process.cwd(), 'src'))
19
+ ? path.resolve(process.cwd(), 'src')
20
+ : process.cwd();
21
+ base = path.resolve(srcDir, importPath.slice(2));
22
+ } else {
23
+ base = path.resolve(dir, importPath);
24
+ }
25
+
26
+ // 1. Direct match (e.g. "./math.pln")
27
+ if (fs.existsSync(base) && fs.statSync(base).isFile()) {
28
+ return base;
29
+ }
30
+ // 2. Implicit .pln extension (e.g. "./math" -> "./math.pln")
31
+ if (fs.existsSync(`${base}.pln`) && fs.statSync(`${base}.pln`).isFile()) {
32
+ return `${base}.pln`;
33
+ }
34
+ // 3. Directory index resolution (e.g. "./utils" -> "./utils/index.pln" or "./utils/app.pln")
35
+ if (fs.existsSync(base) && fs.statSync(base).isDirectory()) {
36
+ const indexPath = path.join(base, 'index.pln');
37
+ if (fs.existsSync(indexPath) && fs.statSync(indexPath).isFile()) {
38
+ return indexPath;
39
+ }
40
+ const appPath = path.join(base, 'app.pln');
41
+ if (fs.existsSync(appPath) && fs.statSync(appPath).isFile()) {
42
+ return appPath;
43
+ }
44
+ }
45
+ return base;
46
+ }
47
+
48
+ // Returns the local file import and re-export paths declared at the top level of an AST.
11
49
  function getImports(ast) {
12
- return ast.body
13
- .filter(node => node.type === 'ImportStatement')
14
- .map(node => node.path);
50
+ const paths = [];
51
+ for (const node of ast.body) {
52
+ if (node.type === 'ImportStatement' && node.path && isLocalImportPath(node.path)) {
53
+ paths.push(node.path);
54
+ } else if (node.type === 'ExportStatement' && node.fromPath && isLocalImportPath(node.fromPath)) {
55
+ paths.push(node.fromPath);
56
+ }
57
+ }
58
+ return paths;
15
59
  }
16
60
 
17
61
  // Resolves all dependencies of entryPath using DFS topological order.
@@ -45,8 +89,8 @@ function resolveDependencies(entryPath) {
45
89
  }
46
90
 
47
91
  // Parse the file to discover its own imports.
48
- // Annotate any tokenise/parse error with the filename so callers see
49
- // "file.pln — Line N, Column N: …" rather than a bare positional message.
92
+ // Annotate any tokenise/parse error with the filename so callers see
93
+ // "file.pln — Line N, Column N: …" rather than a bare positional message.
50
94
  const source = fs.readFileSync(absPath, 'utf8');
51
95
  let tokens, ast;
52
96
  try {
@@ -61,7 +105,7 @@ function resolveDependencies(entryPath) {
61
105
  const newStack = [...stack, absPath];
62
106
  for (const importPath of getImports(ast)) {
63
107
  const dir = path.dirname(absPath);
64
- const resolvedAbs = path.resolve(dir, importPath);
108
+ const resolvedAbs = resolveImportPath(dir, importPath);
65
109
  visit(resolvedAbs, newStack);
66
110
  }
67
111
 
@@ -75,12 +119,39 @@ function resolveDependencies(entryPath) {
75
119
  }
76
120
 
77
121
  // Compile all files in dependency order into one JavaScript string.
78
- function bundle(entryPath) {
122
+ function bundle(entryPath, options = {}) {
79
123
  const files = resolveDependencies(entryPath);
80
- const context = createGenerationContext();
81
- const parts = files.map(({ ast }) => generate(ast, context)).filter(js => js.trim() !== '');
82
- const js = parts.join('\n');
83
- return context.needsAsync ? wrapAsync(js) : js;
124
+ const context = createGenerationContext(options);
125
+ const parts = files.map(({ absPath, ast }) => {
126
+ const relPath = path.relative(process.cwd(), absPath).replace(/\\/g, '/') || path.basename(absPath);
127
+ context.sourceFile = relPath;
128
+ if (context.sourceMapBuilder) {
129
+ try {
130
+ const content = fs.readFileSync(absPath, 'utf8');
131
+ context.sourceMapBuilder.addSource(relPath, content);
132
+ } catch (_) { /* ignore missing content */ }
133
+ }
134
+ const res = generate(ast, context);
135
+ return typeof res === 'string' ? res : (res && res.code ? res.code : '');
136
+ }).filter(js => js && js.trim() !== '');
137
+ let js = parts.join('\n');
138
+ if (context.needsAsync) {
139
+ js = wrapAsync(js);
140
+ if (context.sourceMapBuilder) {
141
+ for (const m of context.sourceMapBuilder.mappings) {
142
+ m.generatedLine += 1;
143
+ }
144
+ }
145
+ }
146
+
147
+ if (options.sourceMap && context.sourceMapBuilder) {
148
+ return {
149
+ code: js,
150
+ map: context.sourceMapBuilder,
151
+ mapObject: context.sourceMapBuilder.toJSON(),
152
+ };
153
+ }
154
+ return js;
84
155
  }
85
156
 
86
157
  module.exports = { bundle, resolveDependencies };
package/compiler/cli.js CHANGED
@@ -88,13 +88,13 @@ ${section('THE LANGUAGE IN EIGHT LINES')}
88
88
  try ... recover as err ... done retry 3 times every 5s errors
89
89
 
90
90
  ${section('ALSO SHIPPED')}
91
- Comparisons and stdlib (v1.0) · PlainScript Expressions (v1.1) ·
92
- JavaScript gateway with ask (v1.1.1) · OCR · Telegram bots ·
93
- WhatsApp bots (v2.1.1) ·
94
- email · schedules · WebSocket · cache (v2.1) ·
95
- sessions · uploads · cookies · rate limits · api keys · OAuth (v2.1.1)
91
+ Comparisons and stdlib · PlainScript Expressions ·
92
+ console input with ask · OCR · Telegram bots ·
93
+ WhatsApp bots ·
94
+ email · schedules · WebSocket · cache ·
95
+ sessions · uploads · cookies · rate limits · api keys · OAuth
96
96
  JSON body · redirect · AI chat/embeddings · vector similarity ·
97
- paginate · collection & string primitives (v2.2)
97
+ paginate · collection & string primitives
98
98
 
99
99
  ${section('FIRST RUN')}
100
100
  plainscript new hello scaffolds hello/ with a live web app
@@ -364,13 +364,13 @@ function ensureDependencies(files, install = true) {
364
364
  // Deterministic only: the lexer/parser/generator pipeline is the single
365
365
  // authoritative compiler. Unsupported syntax produces a precise compiler
366
366
  // error — there is no second compilation path (v2.1.1).
367
- function compile(filePath) {
367
+ function compile(filePath, options = {}) {
368
368
  const absPath = path.resolve(filePath);
369
369
  if (!fs.existsSync(absPath)) {
370
370
  console.error(`File not found: ${filePath}`);
371
371
  process.exit(1);
372
372
  }
373
- const generationContext = createGenerationContext();
373
+ const generationContext = createGenerationContext(options);
374
374
 
375
375
  let files;
376
376
  stage('Resolving imports', () => {
@@ -378,9 +378,38 @@ function compile(filePath) {
378
378
  });
379
379
  stage('Building dependency graph', () => files);
380
380
  stage('Checking runtime dependencies', () => ensureDependencies(files, true));
381
- const js = stage('Generating JavaScript', () =>
382
- files.map(({ ast }) => generate(ast, generationContext)).filter(s => s.trim()).join('\n'));
383
- return generationContext.needsAsync ? wrapAsync(js) : js;
381
+ const parts = stage('Generating JavaScript', () =>
382
+ files.map(({ absPath: fileAbs, ast }) => {
383
+ const relPath = path.relative(process.cwd(), fileAbs).replace(/\\/g, '/') || path.basename(fileAbs);
384
+ generationContext.sourceFile = relPath;
385
+ if (generationContext.sourceMapBuilder) {
386
+ try {
387
+ const content = fs.readFileSync(fileAbs, 'utf8');
388
+ generationContext.sourceMapBuilder.addSource(relPath, content);
389
+ } catch (_) {}
390
+ }
391
+ const res = generate(ast, generationContext);
392
+ return typeof res === 'string' ? res : (res && res.code ? res.code : '');
393
+ }).filter(s => s && s.trim()));
394
+ let js = parts.join('\n');
395
+ if (generationContext.needsAsync) {
396
+ js = wrapAsync(js);
397
+ if (generationContext.sourceMapBuilder) {
398
+ for (const m of generationContext.sourceMapBuilder.mappings) {
399
+ m.generatedLine += 1;
400
+ }
401
+ }
402
+ }
403
+
404
+ if (options.sourceMap && generationContext.sourceMapBuilder) {
405
+ return {
406
+ code: js,
407
+ map: generationContext.sourceMapBuilder,
408
+ mapObject: generationContext.sourceMapBuilder.toJSON(),
409
+ };
410
+ }
411
+
412
+ return js;
384
413
  }
385
414
 
386
415
  // ── Commands ─────────────────────────────────────────────────────────────────
@@ -408,7 +437,14 @@ async function cmdRun(filePath, extraArgs = []) {
408
437
  console.error('Usage: plainscript run <file.pln>');
409
438
  process.exit(1);
410
439
  }
411
- const js = compile(filePath);
440
+ const isSourcemap = process.argv.includes('--sourcemap') || process.argv.includes('-m') || process.env.PLAINSCRIPT_SOURCEMAP === 'true';
441
+ let js;
442
+ if (isSourcemap) {
443
+ const res = compile(filePath, { sourceMap: true, outputFile: 'out.js' });
444
+ js = res.code + '\n' + res.map.toInlineDataUrl() + '\n';
445
+ } else {
446
+ js = compile(filePath);
447
+ }
412
448
  console.log('');
413
449
  // Execute from the entry file's directory so relative assets and CWD-based
414
450
  // behaviour match a direct `node` invocation.
@@ -417,8 +453,9 @@ async function cmdRun(filePath, extraArgs = []) {
417
453
  const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'plainscript-run-'));
418
454
  const tmpFile = path.join(tmpDir, 'out.js');
419
455
  fs.writeFileSync(tmpFile, js, 'utf8');
456
+ const nodeFlags = isSourcemap ? ['--enable-source-maps'] : [];
420
457
  try {
421
- execFileSync(process.execPath, [tmpFile, ...extraArgs], {
458
+ execFileSync(process.execPath, [...nodeFlags, tmpFile, ...extraArgs], {
422
459
  stdio: 'inherit',
423
460
  cwd: entryDir,
424
461
  env: { ...process.env, NODE_PATH: searchPaths.join(path.delimiter) },
@@ -434,19 +471,33 @@ async function cmdRun(filePath, extraArgs = []) {
434
471
 
435
472
  // Compile one entry and write it to outDir with its source name preserved,
436
473
  // relative to the source root when the file lives inside it.
437
- function buildOne(filePath, srcDir, outDir) {
474
+ function buildOne(filePath, srcDir, outDir, options = {}) {
438
475
  const absFile = path.resolve(filePath);
439
476
  if (!fs.existsSync(absFile)) {
440
477
  console.error(`File not found: ${filePath}`);
441
478
  process.exit(1);
442
479
  }
443
- const js = compile(absFile);
444
480
  const srcRoot = path.resolve(srcDir);
445
481
  let rel = path.relative(srcRoot, absFile).replace(/\.pln$/, '.js');
446
482
  if (rel.startsWith('..') || path.isAbsolute(rel)) rel = path.basename(absFile).replace(/\.pln$/, '.js');
447
483
  const outPath = path.join(path.resolve(outDir), rel);
484
+
485
+ const isSourcemap = options.sourceMap || process.argv.includes('--sourcemap') || process.argv.includes('-m') || process.env.PLAINSCRIPT_SOURCEMAP === 'true';
486
+
487
+ let code, mapObject;
488
+ if (isSourcemap) {
489
+ const res = compile(absFile, { sourceMap: true, outputFile: path.basename(outPath) });
490
+ code = res.code + `\n//# sourceMappingURL=${path.basename(outPath)}.map\n`;
491
+ mapObject = res.mapObject;
492
+ } else {
493
+ code = compile(absFile);
494
+ }
495
+
448
496
  fs.mkdirSync(path.dirname(outPath), { recursive: true });
449
- fs.writeFileSync(outPath, js, 'utf8');
497
+ fs.writeFileSync(outPath, code, 'utf8');
498
+ if (mapObject) {
499
+ fs.writeFileSync(outPath + '.map', JSON.stringify(mapObject, null, 2), 'utf8');
500
+ }
450
501
  return path.relative(process.cwd(), outPath) || outPath;
451
502
  }
452
503
 
@@ -525,34 +576,30 @@ function cmdNew(projectName) {
525
576
  fs.mkdirSync(path.join(dir, 'public'));
526
577
  fs.mkdirSync(path.join(dir, 'src'));
527
578
 
528
- // src/app.pln — starter Express app
529
- fs.writeFileSync(path.join(dir, 'src', 'app.pln'), `use express
530
-
531
- remember app as express()
579
+ // src/app.pln — starter web app
580
+ fs.writeFileSync(path.join(dir, 'src', 'app.pln'), `web app
532
581
 
533
582
  serve folder "public"
534
583
 
535
- when someone visits "/"
584
+ route get "/"
536
585
  reply "Hello from PlainScript!"
537
586
  done
538
587
 
539
- when someone visits "/api/status"
588
+ route get "/api/status"
540
589
  reply json
541
590
  status is "ok"
542
- version is "1.0"
591
+ version is "1.0.3"
543
592
  done
544
593
  done
545
594
 
546
- listen on 3000
547
- show "Server running at http://localhost:3000"
548
- done
595
+ start 3000
549
596
  `);
550
597
 
551
598
  // package.json — plain Node semantics; PlainScript itself is a devDependency and
552
599
  // deployment only needs the generated dist/ output.
553
600
  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({
554
601
  name,
555
- version: '1.0.1',
602
+ version: VERSION,
556
603
  description: `A PlainScript v${VERSION} application`,
557
604
  main: 'dist/app.js',
558
605
  scripts: {
@@ -33,6 +33,8 @@ const PACKAGE_MAP = Object.freeze({
33
33
  // through qrcode-terminal. Neither package ever appears in PlainScript source.
34
34
  whatsapp: '@whiskeysockets/baileys',
35
35
  'wa-qrcode': 'qrcode-terminal',
36
+ // v2.2.0 — MongoDB driver.
37
+ mongodb: 'mongodb',
36
38
  });
37
39
 
38
40
  const BUILTIN_MODULES = new Set(builtinModules);
@@ -66,6 +68,12 @@ function visit(node, onUse) {
66
68
 
67
69
  if (node.type === 'UseStatement') {
68
70
  onUse(node.module);
71
+ } else if (node.type === 'ImportStatement' && node.path) {
72
+ // Detect npm package dependencies imported via `bring ... from "pkg"` or `import ... from "pkg"`
73
+ const isLocalFile = node.path.startsWith('.') || node.path.startsWith('/') || node.path.startsWith('\\') || node.path.startsWith('@/') || node.path.endsWith('.pln');
74
+ if (!isLocalFile) {
75
+ onUse(node.path);
76
+ }
69
77
  } else if (node.type === 'WebAppStatement') {
70
78
  // The `web app` shorthand creates an Express application.
71
79
  onUse('express');
@@ -87,6 +95,9 @@ function visit(node, onUse) {
87
95
  } else if (node.type === 'PostgresStatement') {
88
96
  // v2.1.0 — `postgres "<url>"` uses node-postgres under the hood.
89
97
  onUse('postgres');
98
+ } else if (node.type === 'MongoStatement') {
99
+ // v2.2.0 — `mongo "<uri>"` uses mongodb driver under the hood.
100
+ onUse('mongodb');
90
101
  } else if (node.type === 'OcrStatement') {
91
102
  // v2.0.1 — `ocr "<image>" as <variable>` uses tesseract.js under the hood.
92
103
  onUse('ocr');