plainscript-lang 1.0.1 → 1.0.2

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 (52) hide show
  1. package/README.md +154 -147
  2. package/compiler/bundler.js +2 -2
  3. package/compiler/cli.js +58 -58
  4. package/compiler/formatter.js +1 -1
  5. package/compiler/generator.js +753 -67
  6. package/compiler/lexer.js +127 -53
  7. package/compiler/parser.js +953 -151
  8. package/compiler/version.js +1 -1
  9. package/docs/CAPABILITY_GAP_AUDIT.md +130 -29
  10. package/docs/PLAINSCRIPT-SPEC.md +584 -0
  11. package/docs/index.html +33 -42
  12. package/docs/website/script.js +110 -24
  13. package/docs/website/style.css +4 -4
  14. package/examples/arrays.pln +12 -0
  15. package/examples/{auth-api.ps → auth-api.pln} +3 -3
  16. package/examples/{cache-and-jobs.ps → cache-and-jobs.pln} +1 -1
  17. package/examples/{concurrency.ps → concurrency.pln} +8 -8
  18. package/examples/{database.ps → database.pln} +1 -1
  19. package/examples/{deployment.ps → deployment.pln} +2 -2
  20. package/examples/{email-send.ps → email-send.pln} +1 -1
  21. package/examples/{error-handling.ps → error-handling.pln} +8 -7
  22. package/examples/{expressions.ps → expressions.pln} +1 -1
  23. package/examples/{file-uploads.ps → file-uploads.pln} +4 -4
  24. package/examples/{files-and-config.ps → files-and-config.pln} +4 -4
  25. package/examples/football-backend/{app.ps → app.pln} +2 -2
  26. package/examples/{http-client.ps → http-client.pln} +18 -18
  27. package/examples/id-verification/{app.ps → app.pln} +1 -1
  28. package/examples/{loops.ps → loops.pln} +2 -3
  29. package/examples/modules/{app.ps → app.pln} +4 -4
  30. package/examples/modules/{math.ps → math.pln} +1 -1
  31. package/examples/{record-kinds.ps → record-kinds.pln} +4 -4
  32. package/examples/{rest-api-fetch.ps → rest-api-fetch.pln} +1 -1
  33. package/examples/{rest-api.ps → rest-api.pln} +5 -5
  34. package/examples/{scheduled-tasks.ps → scheduled-tasks.pln} +2 -2
  35. package/examples/{search-and-filter.ps → search-and-filter.pln} +5 -5
  36. package/examples/{sessions-and-cookies.ps → sessions-and-cookies.pln} +2 -2
  37. package/examples/start.pln +2 -0
  38. package/examples/{stdlib.ps → stdlib.pln} +2 -2
  39. package/examples/{telegram-bot.ps → telegram-bot.pln} +2 -2
  40. package/examples/{websocket-server.ps → websocket-server.pln} +1 -1
  41. package/package.json +1 -1
  42. package/docs/PLINJS_SPEC.md +0 -1151
  43. package/examples/arrays.ps +0 -13
  44. package/examples/start.ps +0 -2
  45. /package/examples/{day2.ps → day2.pln} +0 -0
  46. /package/examples/{day3.ps → day3.pln} +0 -0
  47. /package/examples/{hello.ps → hello.pln} +0 -0
  48. /package/examples/{objects.ps → objects.pln} +0 -0
  49. /package/examples/{server.ps → server.pln} +0 -0
  50. /package/examples/{web-app.ps → web-app.pln} +0 -0
  51. /package/examples/whatsapp-bot/{pairing.ps → pairing.pln} +0 -0
  52. /package/examples/whatsapp-bot/{qr.ps → qr.pln} +0 -0
@@ -45,8 +45,8 @@ function resolveDependencies(entryPath) {
45
45
  }
46
46
 
47
47
  // Parse the file to discover its own imports.
48
- // Annotate any tokenise/parse error with the filename so callers see
49
- // "file.ps — Line N, Column N: …" rather than a bare positional message.
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.
50
50
  const source = fs.readFileSync(absPath, 'utf8');
51
51
  let tokens, ast;
52
52
  try {
package/compiler/cli.js CHANGED
@@ -1,21 +1,21 @@
1
1
  #!/usr/bin/env node
2
- // CLI: compile and run PlainScript (.ps) files.
2
+ // CLI: compile and run PlainScript (.pln) files.
3
3
  //
4
- // Usage:
5
- // plainscript run <file.ps> install missing dependencies, compile and execute
6
- // plainscript build [file.ps] compile src/ (or one file) to dist/, names preserved
7
- // plainscript check [target] fully validate source(s): imports + generate + JS syntax
8
- // (target: a .ps file, a directory, or none to scan the project)
9
- // plainscript fmt <file.ps> format a PlainScript file in-place
10
- // plainscript new [name] scaffold a new PlainScript project
11
- // plainscript install install dependencies detected in the project's sources
12
- // plainscript start build src/app.ps (or index.ps) and run its dist output
13
- // plainscript doctor check the PlainScript project environment
14
- // plainscript add <package> install a package into the project
15
- // plainscript remove <package> uninstall a package from the project
16
- // plainscript update update all installed packages
17
- // plainscript version print the compiler version
18
- // plainscript help print this help text
4
+ // Usage:
5
+ // plainscript run <file.pln> install missing dependencies, compile and execute
6
+ // plainscript build [file.pln] compile src/ (or one file) to dist/, names preserved
7
+ // plainscript check [target] fully validate source(s): imports + generate + JS syntax
8
+ // (target: a .pln file, a directory, or none to scan the project)
9
+ // plainscript fmt <file.pln> format a PlainScript file in-place
10
+ // plainscript new [name] scaffold a new PlainScript project
11
+ // plainscript install install dependencies detected in the project's sources
12
+ // plainscript start build src/app.pln (or index.pln) and run its dist output
13
+ // plainscript doctor check the PlainScript project environment
14
+ // plainscript add <package> install a package into the project
15
+ // plainscript remove <package> uninstall a package from the project
16
+ // plainscript update update all installed packages
17
+ // plainscript version print the compiler version
18
+ // plainscript help print this help text
19
19
 
20
20
  const fs = require('fs');
21
21
  const path = require('path');
@@ -51,20 +51,20 @@ function warn(message) {
51
51
  const section = (title) => `\n${clrCyan(clrBold(title))}`;
52
52
 
53
53
  const HELP = `
54
- ${clrBold(`PlainScript v${VERSION}`)} ${clrDim('· .ps compiles to readable Node.js')}
54
+ ${clrBold(`PlainScript v${VERSION}`)} ${clrDim('· .pln compiles to readable Node.js')}
55
55
 
56
56
  ${section('START')}
57
- plainscript new [name] Scaffold a new project with a working app.ps
58
- plainscript run <file.ps> Install missing deps, compile, execute
59
- plainscript start Build src/app.ps and run it from dist/
57
+ plainscript new [name] Scaffold a new project with a working app.pln
58
+ plainscript run <file.pln> Install missing deps, compile, execute
59
+ plainscript start Build src/app.pln and run it from dist/
60
60
 
61
61
  ${section('BUILD & CHECK')}
62
- plainscript build Compile every .ps under src/ into dist/
63
- plainscript build <file.ps> Compile one file into dist/ (name preserved)
62
+ plainscript build Compile every .pln under src/ into dist/
63
+ plainscript build <file.pln> Compile one file into dist/ (name preserved)
64
64
  plainscript check [target] Validate imports + generate + JS output (no writes)
65
- target: a .ps file, a directory, or none = project scan
65
+ target: a .pln file, a directory, or none = project scan
66
66
  --json emits deterministic machine-readable output
67
- plainscript fmt <file.ps> Format a file in place
67
+ plainscript fmt <file.pln> Format a file in place
68
68
 
69
69
  ${section('PACKAGES')}
70
70
  plainscript install Install everything your source needs
@@ -98,7 +98,7 @@ ${section('ALSO SHIPPED')}
98
98
 
99
99
  ${section('FIRST RUN')}
100
100
  plainscript new hello scaffolds hello/ with a live web app
101
- plainscript run hello/app.ps serves it at http://localhost:3000
101
+ plainscript run hello/app.pln serves it at http://localhost:3000
102
102
  `.trim();
103
103
 
104
104
  // ── npm invocation ────────────────────────────────────────────────────────────
@@ -151,8 +151,8 @@ function isValidPackageName(name) {
151
151
  // "exclude": ["vendor"] } }
152
152
  //
153
153
  // Filenames and folder structure are always preserved:
154
- // src/messi.ps → dist/messi.js
155
- // src/helpers/math.ps → dist/helpers/math.js
154
+ // src/messi.pln → dist/messi.js
155
+ // src/helpers/math.pln → dist/helpers/math.js
156
156
  const SOURCE_DIR = 'src';
157
157
  const DEFAULT_OUT_DIR = 'dist';
158
158
 
@@ -185,7 +185,7 @@ function resolveOutDir(opts) {
185
185
  return DEFAULT_OUT_DIR;
186
186
  }
187
187
 
188
- // Every .ps file under srcDir, recursively, as paths relative to srcDir.
188
+ // Every .pln file under srcDir, recursively, as paths relative to srcDir.
189
189
  // Deterministic order (sorted); node_modules, hidden directories, the output
190
190
  // directory, and any user-specified exclude patterns are skipped.
191
191
  function discoverSources(srcDir, outDir, exclude) {
@@ -208,7 +208,7 @@ function discoverSources(srcDir, outDir, exclude) {
208
208
  try { stat = fs.statSync(full); } catch (_) { continue; }
209
209
  if (stat.isDirectory()) {
210
210
  walk(full);
211
- } else if (name.endsWith('.ps')) {
211
+ } else if (name.endsWith('.pln')) {
212
212
  found.push(path.relative(root, full));
213
213
  }
214
214
  }
@@ -405,7 +405,7 @@ function nodeModulesSearchPaths(entryDir) {
405
405
 
406
406
  async function cmdRun(filePath, extraArgs = []) {
407
407
  if (!filePath) {
408
- console.error('Usage: plainscript run <file.ps>');
408
+ console.error('Usage: plainscript run <file.pln>');
409
409
  process.exit(1);
410
410
  }
411
411
  const js = compile(filePath);
@@ -442,8 +442,8 @@ function buildOne(filePath, srcDir, outDir) {
442
442
  }
443
443
  const js = compile(absFile);
444
444
  const srcRoot = path.resolve(srcDir);
445
- let rel = path.relative(srcRoot, absFile).replace(/\.ps$/, '.js');
446
- if (rel.startsWith('..') || path.isAbsolute(rel)) rel = path.basename(absFile).replace(/\.ps$/, '.js');
445
+ let rel = path.relative(srcRoot, absFile).replace(/\.pln$/, '.js');
446
+ if (rel.startsWith('..') || path.isAbsolute(rel)) rel = path.basename(absFile).replace(/\.pln$/, '.js');
447
447
  const outPath = path.join(path.resolve(outDir), rel);
448
448
  fs.mkdirSync(path.dirname(outPath), { recursive: true });
449
449
  fs.writeFileSync(outPath, js, 'utf8');
@@ -453,16 +453,16 @@ function buildOne(filePath, srcDir, outDir) {
453
453
  // `plainscript build` — TypeScript-style production build:
454
454
  //
455
455
  // Zero config (default):
456
- // messi.ps → dist/messi.js (project-root sources)
457
- // src/index.ps → dist/index.js (src/ is the source root)
458
- // src/a/b.ps → dist/a/b.js (structure preserved)
456
+ // messi.pln → dist/messi.js (project-root sources)
457
+ // src/index.pln → dist/index.js (src/ is the source root)
458
+ // src/a/b.pln → dist/a/b.js (structure preserved)
459
459
  //
460
460
  // With plainscript.config.json:
461
461
  // { "compilerOptions": { "outDir": "./build", "rootDir": "./lib" } }
462
- // lib/app.ps → build/app.js
462
+ // lib/app.pln → build/app.js
463
463
  //
464
464
  // With an explicit file argument only that entry is compiled; without one,
465
- // every .ps under the discovered source root builds to the output directory.
465
+ // every .pln under the discovered source root builds to the output directory.
466
466
  async function cmdBuild(filePath) {
467
467
  const opts = readCompilerOptions();
468
468
  const srcDir = resolveSrcDir(opts);
@@ -475,7 +475,7 @@ async function cmdBuild(filePath) {
475
475
  }
476
476
  const sources = discoverSources(srcDir, outDir, exclude);
477
477
  if (sources.length === 0) {
478
- console.error(`No .ps files found under "${srcDir}".`);
478
+ console.error(`No .pln files found under "${srcDir}".`);
479
479
  process.exit(1);
480
480
  }
481
481
  QUIET_STAGES = true;
@@ -500,7 +500,7 @@ async function cmdStart(extraArgs = []) {
500
500
  const outDir = resolveOutDir(opts);
501
501
  const entryPath = findEntry(opts);
502
502
  if (!entryPath) {
503
- console.error('No entry file found. Expected "src/app.ps" or "src/index.ps".');
503
+ console.error('No entry file found. Expected "src/app.pln" or "src/index.pln".');
504
504
  process.exit(1);
505
505
  }
506
506
  const outFile = buildOne(entryPath, srcDir, outDir);
@@ -525,8 +525,8 @@ function cmdNew(projectName) {
525
525
  fs.mkdirSync(path.join(dir, 'public'));
526
526
  fs.mkdirSync(path.join(dir, 'src'));
527
527
 
528
- // src/app.ps — starter Express app
529
- fs.writeFileSync(path.join(dir, 'src', 'app.ps'), `use express
528
+ // src/app.pln — starter Express app
529
+ fs.writeFileSync(path.join(dir, 'src', 'app.pln'), `use express
530
530
 
531
531
  remember app as express()
532
532
 
@@ -584,7 +584,7 @@ Then open http://localhost:3000 in your browser.
584
584
  `);
585
585
 
586
586
  console.log(`✓ Created project "${name}"`);
587
- console.log(`\nNext steps:\n cd ${name}\n npm install\n npx plainscript run src/app.ps`);
587
+ console.log(`\nNext steps:\n cd ${name}\n npm install\n npx plainscript run src/app.pln`);
588
588
  }
589
589
 
590
590
  // ── plainscript install ────────────────────────────────────────────────────────────
@@ -594,11 +594,11 @@ Then open http://localhost:3000 in your browser.
594
594
  function findEntry(opts) {
595
595
  const srcDir = resolveSrcDir(opts);
596
596
  const candidates = [
597
- path.join(srcDir, 'app.ps'),
598
- path.join(srcDir, 'index.ps'),
597
+ path.join(srcDir, 'app.pln'),
598
+ path.join(srcDir, 'index.pln'),
599
599
  ];
600
600
  if (srcDir !== '.') {
601
- candidates.push('app.ps', 'index.ps');
601
+ candidates.push('app.pln', 'index.pln');
602
602
  }
603
603
  return candidates.find((c) => fs.existsSync(path.resolve(c))) || null;
604
604
  }
@@ -613,7 +613,7 @@ function collectSourceAsts() {
613
613
  const exclude = opts && opts.exclude;
614
614
  const sources = discoverSources(srcDir, outDir, exclude);
615
615
  if (sources.length === 0) {
616
- console.error(`No .ps source files found under "${srcDir}".`);
616
+ console.error(`No .pln source files found under "${srcDir}".`);
617
617
  process.exit(1);
618
618
  }
619
619
  const root = path.resolve(srcDir);
@@ -669,14 +669,14 @@ function cmdDoctor() {
669
669
  check('Runtime', fs.existsSync(path.join(__dirname, 'generator.js')));
670
670
  console.log('');
671
671
 
672
- // Source discovery check: does the project have any .ps files?
672
+ // Source discovery check: does the project have any .pln files?
673
673
  const opts = readCompilerOptions();
674
674
  const srcDir = resolveSrcDir(opts);
675
675
  const outDir = resolveOutDir(opts);
676
676
  const exclude = opts && opts.exclude;
677
677
  const sources = discoverSources(srcDir, outDir, exclude);
678
678
  check('Source files', sources.length > 0,
679
- sources.length > 0 ? `"${srcDir}/" discovered (${sources.length} file(s))` : `no .ps files under "${srcDir}"`);
679
+ sources.length > 0 ? `"${srcDir}/" discovered (${sources.length} file(s))` : `no .pln files under "${srcDir}"`);
680
680
  if (sources.length === 0) return;
681
681
 
682
682
  // Dependency check: scan every source file for npm imports
@@ -751,7 +751,7 @@ function cmdUpdate() {
751
751
  }
752
752
 
753
753
  // Check syntax of a PlainScript file without generating JavaScript or executing.
754
- // Full validation of a single .ps entry: resolve imports, parse+generate every
754
+ // Full validation of a single .pln entry: resolve imports, parse+generate every
755
755
  // file in dependency order, and verify the emitted JavaScript is syntactically
756
756
  // valid — all without writing anything to disk. Returns a deterministic
757
757
  // result record; `deps` are the npm packages the sources require.
@@ -760,7 +760,7 @@ function validateSource(absPath) {
760
760
  const t0 = Date.now();
761
761
  try {
762
762
  // resolveDependencies parses each file too, so a parse error anywhere in
763
- // the import graph surfaces here with a "file.ps — Line:Col" prefix.
763
+ // the import graph surfaces here with a "file.pln — Line:Col" prefix.
764
764
  const files = resolveDependencies(absPath);
765
765
  const context = createGenerationContext();
766
766
  let js = files.map(({ ast }) => generate(ast, context)).filter(s => s.trim()).join('\n');
@@ -787,14 +787,14 @@ function validateSource(absPath) {
787
787
 
788
788
  // `plainscript check [target] [--json]`
789
789
  //
790
- // Fully validates one .ps file, every .ps under a directory, or (with no
790
+ // Fully validates one .pln file, every .pln under a directory, or (with no
791
791
  // target) the project sources, deterministically and non-interactively:
792
792
  // resolve imports, parse + generate, and confirm the JS output parses. Never
793
793
  // prompts, never writes files, never installs packages.
794
794
  //
795
- // plainscript check validate every .ps in the project source root
796
- // plainscript check app.ps validate one file (and its imports)
797
- // plainscript check src/ validate every .ps under a directory
795
+ // plainscript check validate every .pln in the project source root
796
+ // plainscript check app.pln validate one file (and its imports)
797
+ // plainscript check src/ validate every .pln under a directory
798
798
  // plainscript check --json machine-readable JSON on stdout
799
799
  function cmdCheck(target, json) {
800
800
  const opts = readCompilerOptions();
@@ -807,7 +807,7 @@ function cmdCheck(target, json) {
807
807
  const abs = path.resolve(target);
808
808
  if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
809
809
  sources = discoverSources(abs, outDir, exclude).map(r => path.join(abs, r));
810
- } else if (/\.ps$/.test(target) && !fs.existsSync(abs)) {
810
+ } else if (/\.pln$/.test(target) && !fs.existsSync(abs)) {
811
811
  if (json) {
812
812
  console.log(JSON.stringify({
813
813
  plainscript: VERSION, ok: false,
@@ -825,7 +825,7 @@ function cmdCheck(target, json) {
825
825
  const root = path.resolve(srcDir);
826
826
  sources = discoverSources(srcDir, outDir, exclude).map(r => path.join(root, r));
827
827
  if (sources.length === 0) {
828
- const msg = `No .ps files found under "${srcDir}".`;
828
+ const msg = `No .pln files found under "${srcDir}".`;
829
829
  if (json) console.log(JSON.stringify({ plainscript: VERSION, ok: false, sources: [], summary: { total: 0, passed: 0, failed: 1 }, errors: [{ file: srcDir, error: msg }] }));
830
830
  else console.error(msg);
831
831
  process.exit(1);
@@ -877,7 +877,7 @@ function cmdCheck(target, json) {
877
877
  // Format a PlainScript file in-place.
878
878
  function cmdFmt(filePath) {
879
879
  if (!filePath) {
880
- console.error('Usage: plainscript fmt <file.ps>');
880
+ console.error('Usage: plainscript fmt <file.pln>');
881
881
  process.exit(1);
882
882
  }
883
883
  const absPath = path.resolve(filePath);
@@ -937,7 +937,7 @@ async function main() {
937
937
  case 'help': cmdHelp(); break;
938
938
  default:
939
939
  // Backwards-compatible: treat the first arg as a file to run directly
940
- if (command && command.endsWith('.ps')) {
940
+ if (command && command.endsWith('.pln')) {
941
941
  await cmdRun(command);
942
942
  } else {
943
943
  console.error(`Unknown command: "${command}". Run "plainscript help" for usage.`);
@@ -17,7 +17,7 @@ const INDENT_STARTERS = [
17
17
  /^make\s+\S+\s*\(/, // make name(...)
18
18
  /^if\s+/, // if ...
19
19
  /^otherwise\b/, // otherwise
20
- /^for\s+(each|every)\s+/, // for each ... / for every ...
20
+ /^for\s+each\s+/, // for each ...
21
21
  /^while\s+/, // while ...
22
22
  /^when\s+someone\s+visits/, // when someone visits ...
23
23
  /^when\s+someone\s+(sends|clicks)\b/, // when someone sends / clicks (Telegram)