apexfile 1.1.0

package/bin/cli.js

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * ApexDoc CLI
+ * Usage: apex <command> [options] <file>
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const apex = require('./index');
+
+const VERSION = '1.0.0';
+
+// ── Arg Parsing ─────────────────────────────────────────────────
+
+const args    = process.argv.slice(2);
+const command = args[0];
+const flags   = parseFlags(args.slice(1));
+
+function parseFlags(argv) {
+  const result = { _: [] };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        result[key] = next;
+        i += 2;
+      } else {
+        result[key] = true;
+        i++;
+      }
+    } else {
+      result._.push(arg);
+      i++;
+    }
+  }
+  return result;
+}
+
+// ── Command Router ──────────────────────────────────────────────
+
+switch (command) {
+  case 'build':   cmdBuild();   break;
+  case 'export':  cmdExport();  break;
+  case 'serve':   cmdServe();   break;
+  case 'lint':    cmdLint();    break;
+  case 'ast':     cmdAst();     break;
+  case 'format':  cmdFormat();  break;
+  case 'new':     cmdNew();     break;
+  case 'plugin':  cmdPlugin();  break;
+  case 'theme':   cmdTheme();   break;
+  case '--version':
+  case '-v':      console.log(`apexdoc v${VERSION}`); break;
+  case 'help':
+  case '--help':
+  case '-h':      printHelp(); break;
+  default:
+    if (!command) printHelp();
+    else die(`Unknown command: "${command}". Run "apex help" for usage.`);
+}
+
+// ── Commands ────────────────────────────────────────────────────
+
+function cmdBuild() {
+  const file   = flags._[0];
+  const target = flags.to || 'html';
+  const out    = flags.out;
+
+  requireFile(file);
+
+  log(`Building ${file} → ${target.toUpperCase()}`);
+
+  try {
+    const outPath = apex.export(file, target, out ? path.join(out, outputName(file, target)) : null);
+    ok(`Output → ${outPath}`);
+  } catch (err) {
+    die(err.message);
+  }
+}
+
+function cmdExport() {
+  // Alias for build with explicit --to
+  cmdBuild();
+}
+
+function cmdServe() {
+  const file = flags._[0];
+  const port = parseInt(flags.port || flags.p || '3000');
+
+  requireFile(file);
+
+  try {
+    const http = require('http');
+
+    const respond = (res) => {
+      try {
+        const html = apex.compile(file, 'html');
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(html);
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'text/plain' });
+        res.end('ApexDoc error:\n' + err.message);
+      }
+    };
+
+    const server = http.createServer((req, res) => {
+      if (req.url === '/favicon.ico') { res.end(); return; }
+      respond(res);
+    });
+
+    server.listen(port, () => {
+      ok(`Serving ${file} at http://localhost:${port}`);
+      log('Press Ctrl+C to stop. File changes will reflect on refresh.');
+    });
+
+  } catch (err) {
+    die('Could not start server: ' + err.message);
+  }
+}
+
+function cmdLint() {
+  const file = flags._[0];
+  requireFile(file);
+
+  log(`Linting ${file}...`);
+
+  const result = apex.lint(file);
+
+  if (result.errors.length > 0) {
+    result.errors.forEach(e => {
+      console.error(`  ${red('✗')} [${e.code}] Line ${e.line}: ${e.message}`);
+    });
+  }
+
+  if (result.warnings.length > 0) {
+    result.warnings.forEach(w => {
+      console.warn(`  ${yellow('⚠')} [${w.code}] Line ${w.line}: ${w.message}`);
+    });
+  }
+
+  if (result.valid) {
+    ok(`No errors found.${result.warnings.length > 0 ? ` (${result.warnings.length} warning(s))` : ''}`);
+  } else {
+    die(`${result.errors.length} error(s) found.`);
+  }
+}
+
+function cmdAst() {
+  const file = flags._[0];
+  requireFile(file);
+
+  log(`Inspecting AST for ${file}...`);
+  const json = apex.inspect(file);
+
+  if (flags.out) {
+    fs.writeFileSync(flags.out, json, 'utf8');
+    ok(`AST written to ${flags.out}`);
+  } else {
+    console.log(json);
+  }
+}
+
+function cmdFormat() {
+  const file = flags._[0];
+  requireFile(file);
+
+  // Basic formatter: normalize indentation, trim trailing spaces
+  const source   = fs.readFileSync(file, 'utf8');
+  const lines    = source.split('\n');
+  let   depth    = 0;
+  const indent   = '  ';
+
+  const formatted = lines.map(line => {
+    const t = line.trim();
+    if (!t) return '';
+
+    // Dedent on %%end
+    if (t === '%%end') depth = Math.max(0, depth - 1);
+
+    const result = depth > 0 ? indent.repeat(depth) + t : t;
+
+    // Indent after section/block open
+    if (t.startsWith('%%') && !t.startsWith('%%end') && !t.includes('%%end')) {
+      depth++;
+    }
+
+    return result;
+  });
+
+  const output = formatted.join('\n');
+
+  if (flags.check) {
+    if (output !== source) {
+      console.log('File would be reformatted.');
+      process.exit(1);
+    } else {
+      ok('File is already formatted.');
+    }
+  } else {
+    fs.writeFileSync(file, output, 'utf8');
+    ok(`Formatted ${file}`);
+  }
+}
+
+function cmdNew() {
+  const name     = flags._[0] || 'document.apx';
+  const type     = flags.template || flags.t || 'document';
+  const filePath = name.endsWith('.apx') ? name : name + '.apx';
+
+  if (fs.existsSync(filePath) && !flags.force) {
+    die(`File already exists: ${filePath}. Use --force to overwrite.`);
+  }
+
+  const content = apex.template(type);
+  fs.writeFileSync(filePath, content, 'utf8');
+  ok(`Created ${filePath} (template: ${type})`);
+  log(`Edit it and run: apex serve ${filePath}`);
+}
+
+function cmdPlugin() {
+  const sub = flags._[0];
+
+  if (sub === 'list') {
+    log('Installed plugins: (none — plugin registry coming soon)');
+    return;
+  }
+
+  if (sub === 'install') {
+    const name = flags._[1];
+    if (!name) die('Usage: apex plugin install <name>');
+    log(`Installing plugin: ${name}...`);
+    log('Plugin registry coming in v1.1.0');
+    return;
+  }
+
+  if (sub === 'remove') {
+    const name = flags._[1];
+    if (!name) die('Usage: apex plugin remove <name>');
+    log(`Removing plugin: ${name}...`);
+    log('Plugin registry coming in v1.1.0');
+    return;
+  }
+
+  die('Usage: apex plugin <install|remove|list> [name]');
+}
+
+function cmdTheme() {
+  const sub = flags._[0];
+
+  const builtins = [
+    'default', 'dark-ocean', 'neon-city', 'sunset',
+    'minimal-light', 'forest', 'candy', 'terminal', 'academic', 'newspaper'
+  ];
+
+  if (sub === 'list') {
+    log('Built-in themes:');
+    builtins.forEach(t => console.log(`  • ${t}`));
+    return;
+  }
+
+  if (sub === 'preview') {
+    const name = flags._[1];
+    if (!name) die('Usage: apex theme preview <name>');
+    if (!builtins.includes(name)) die(`Unknown theme: ${name}`);
+    log(`Preview for "${name}" coming in v1.1.0`);
+    return;
+  }
+
+  die('Usage: apex theme <list|preview> [name]');
+}
+
+// ── Help ────────────────────────────────────────────────────────
+
+function printHelp() {
+  console.log(`
+  ${bold('apex')} — ApexDoc CLI v${VERSION}
+
+  ${bold('USAGE')}
+    apex <command> [options] <file.apx>
+
+  ${bold('COMMANDS')}
+    build   <file>              Build .apx to HTML (default)
+    export  <file> --to <fmt>   Export to: html, pdf, text, md, json
+    serve   <file> [--port N]   Serve with live preview
+    lint    <file>              Validate syntax and structure
+    ast     <file>              Inspect the parsed AST
+    format  <file>              Auto-format the source file
+    new     <name> [--template] Create a new .apx file
+    plugin  install|remove|list Manage plugins
+    theme   list|preview        Browse themes
+
+  ${bold('OPTIONS')}
+    --to <target>   Export target: html (default), pdf, text, md, json
+    --out <dir>     Output directory
+    --port <n>      Port for serve command (default: 3000)
+    --template <t>  Template for new: document, presentation, report
+    --force         Overwrite existing files
+    --version       Show version
+
+  ${bold('EXAMPLES')}
+    apex build report.apx
+    apex build report.apx --to pdf --out ./dist
+    apex serve slides.apx --port 4000
+    apex lint doc.apx
+    apex new mydoc.apx --template report
+    apex theme list
+  `);
+}
+
+// ── Helpers ─────────────────────────────────────────────────────
+
+function requireFile(file) {
+  if (!file) die('No file specified. Usage: apex <command> <file.apx>');
+  if (!fs.existsSync(file)) die(`File not found: ${file}`);
+}
+
+function outputName(file, target) {
+  const ext = { html: '.html', text: '.txt', json: '.json', md: '.md', pdf: '.pdf' };
+  return path.basename(file, '.apx') + (ext[target] || '.html');
+}
+
+function log(msg)  { console.log(`  ${cyan('›')} ${msg}`); }
+function ok(msg)   { console.log(`  ${green('✓')} ${msg}`); }
+function die(msg)  { console.error(`  ${red('✗')} ${msg}`); process.exit(1); }
+
+function bold(s)   { return `\x1b[1m${s}\x1b[0m`; }
+function red(s)    { return `\x1b[31m${s}\x1b[0m`; }
+function green(s)  { return `\x1b[32m${s}\x1b[0m`; }
+function yellow(s) { return `\x1b[33m${s}\x1b[0m`; }
+function cyan(s)   { return `\x1b[36m${s}\x1b[0m`; }

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "apexfile",
+  "version": "1.1.0",
+  "description": "The last document format you'll ever need. A unified format with Markdown, LaTeX, SCSS, animations, live data, charts, themes and more — all from a single .apx file.",
+  "main": "src/index.js",
+  "bin": {
+    "apex": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "node test/index.js",
+    "build": "node bin/cli.js build",
+    "serve": "node bin/cli.js serve",
+    "lint": "node bin/cli.js lint",
+    "prepublishOnly": "node test/index.js"
+  },
+  "keywords": [
+    "apexdoc",
+    "apx",
+    "document",
+    "format",
+    "parser",
+    "renderer",
+    "markdown",
+    "latex",
+    "template",
+    "themes",
+    "animations",
+    "charts",
+    "html",
+    "pdf",
+    "presentation",
+    "slides",
+    "documentation"
+  ],
+  "author": "Boniface Njuguna (https://github.com/bonifacenjuguna)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bonifacenjuguna/apexdoc.git"
+  },
+  "homepage": "https://apex.run",
+  "bugs": {
+    "url": "https://github.com/bonifacenjuguna/apexdoc/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {},
+  "directories": {
+    "test": "test"
+  },
+  "type": "commonjs"
+}

package/src/ast/index.js

@@ -0,0 +1,260 @@
+'use strict';
+
+/**
+ * ApexDoc AST Node Factories
+ * Every node in the AST is created via one of these functions.
+ * This ensures a consistent, predictable tree structure.
+ */
+
+const Node = {
+
+  // ── Document Root ───────────────────────────────────────────────
+  document: (meta, style, body) => ({
+    type:  'Document',
+    meta:  meta  || {},
+    style: style || {},
+    body:  body  || [],
+  }),
+
+  // ── META ────────────────────────────────────────────────────────
+  meta: (fields) => ({
+    type:   'Meta',
+    fields: fields || {},
+  }),
+
+  // ── STYLE ───────────────────────────────────────────────────────
+  style: (variables, themes, directives) => ({
+    type:       'Style',
+    variables:  variables  || {},   // { '--primary': '#00f5d4' }
+    themes:     themes     || {},   // { 'dark-ocean': { '--bg': '...' } }
+    directives: directives || [],   // @import, @media, @breakpoint
+  }),
+
+  theme: (name, variables) => ({
+    type:      'Theme',
+    name,
+    variables: variables || {},
+  }),
+
+  styleDirective: (directive, value) => ({
+    type:      'StyleDirective',
+    directive, // @import @media @breakpoint
+    value,
+  }),
+
+  // ── HEADINGS ────────────────────────────────────────────────────
+  heading: (level, children, props, line) => ({
+    type:     'Heading',
+    level:    level || 1,
+    children: children || [],
+    props:    props  || {},
+    line,
+  }),
+
+  // ── TEXT NODES ──────────────────────────────────────────────────
+  text: (value, line) => ({
+    type:  'Text',
+    value: value || '',
+    line,
+  }),
+
+  bold: (children, line) => ({
+    type:     'Bold',
+    children: children || [],
+    line,
+  }),
+
+  italic: (children, line) => ({
+    type:     'Italic',
+    children: children || [],
+    line,
+  }),
+
+  underline: (children, line) => ({
+    type:     'Underline',
+    children: children || [],
+    line,
+  }),
+
+  strikethrough: (children, line) => ({
+    type:     'Strikethrough',
+    children: children || [],
+    line,
+  }),
+
+  superscript: (children, line) => ({
+    type:     'Superscript',
+    children: children || [],
+    line,
+  }),
+
+  subscript: (children, line) => ({
+    type:     'Subscript',
+    children: children || [],
+    line,
+  }),
+
+  codeInline: (value, line) => ({
+    type:  'CodeInline',
+    value: value || '',
+    line,
+  }),
+
+  highlight: (children, line) => ({
+    type:     'Highlight',
+    children: children || [],
+    line,
+  }),
+
+  inlineStyled: (children, props, line) => ({
+    type:     'InlineStyled',
+    children: children || [],
+    props:    props    || {},
+    line,
+  }),
+
+  link: (children, href, line) => ({
+    type:     'Link',
+    children: children || [],
+    href:     href     || '',
+    line,
+  }),
+
+  // ── PARAGRAPH ───────────────────────────────────────────────────
+  paragraph: (children, line) => ({
+    type:     'Paragraph',
+    children: children || [],
+    line,
+  }),
+
+  // ── BLOCKQUOTE ──────────────────────────────────────────────────
+  blockquote: (children, level, line) => ({
+    type:     'Blockquote',
+    children: children || [],
+    level:    level    || 1,
+    line,
+  }),
+
+  // ── HORIZONTAL RULE ─────────────────────────────────────────────
+  hr: (style, line) => ({
+    type:  'HR',
+    style: style || '---',
+    line,
+  }),
+
+  // ── LISTS ───────────────────────────────────────────────────────
+  list: (items, ordered, line) => ({
+    type:     'List',
+    ordered:  ordered || false,
+    items:    items   || [],
+    line,
+  }),
+
+  listItem: (children, indent, line) => ({
+    type:     'ListItem',
+    children: children || [],
+    indent:   indent   || 0,
+    line,
+  }),
+
+  taskItem: (children, state, indent, line) => ({
+    type:     'TaskItem',
+    children: children || [],
+    state:    state    || 'todo', // 'todo' | 'done' | 'progress'
+    indent:   indent   || 0,
+    line,
+  }),
+
+  // ── MATH ────────────────────────────────────────────────────────
+  mathInline: (value, line) => ({
+    type:  'MathInline',
+    value: value || '',
+    line,
+  }),
+
+  mathBlock: (value, props, line) => ({
+    type:    'MathBlock',
+    value:   value || '',
+    props:   props || {},
+    dialect: props?.dialect || 'latex',
+    line,
+  }),
+
+  // ── EXPRESSION / VARIABLE ───────────────────────────────────────
+  expression: (value, line) => ({
+    type:  'Expression',
+    value: value || '',
+    line,
+  }),
+
+  // ── FOOTNOTES ───────────────────────────────────────────────────
+  footnoteRef: (id, line) => ({
+    type: 'FootnoteRef',
+    id,
+    line,
+  }),
+
+  footnoteDef: (id, content, line) => ({
+    type:    'FootnoteDef',
+    id,
+    content: content || '',
+    line,
+  }),
+
+  // ── LOGIC ───────────────────────────────────────────────────────
+  setVar: (name, value, line) => ({
+    type:  'SetVar',
+    name,
+    value,
+    line,
+  }),
+
+  conditional: (condition, consequent, alternates, fallback, line) => ({
+    type:       'Conditional',
+    condition,
+    consequent: consequent || [],  // if branch
+    alternates: alternates || [],  // elseif branches [ { condition, body } ]
+    fallback:   fallback   || [],  // else branch
+    line,
+  }),
+
+  loop: (variable, source, body, line) => ({
+    type:     'Loop',
+    variable, // iteration variable name
+    source,   // source expression string
+    body:     body || [],
+    line,
+  }),
+
+  keyframe: (name, steps, line) => ({
+    type:  'Keyframe',
+    name,
+    steps: steps || {},
+    line,
+  }),
+
+  // ── GENERIC BLOCK ───────────────────────────────────────────────
+  block: (name, props, children, line) => ({
+    type:     'Block',
+    name:     name     || 'unknown',
+    props:    props    || {},
+    children: children || [],
+    line,
+  }),
+
+  // ── SELF-CLOSING BLOCK ──────────────────────────────────────────
+  selfCloseBlock: (name, props, line) => ({
+    type:  'SelfCloseBlock',
+    name:  name  || 'unknown',
+    props: props || {},
+    line,
+  }),
+
+  // ── NEWLINE ─────────────────────────────────────────────────────
+  newline: (line) => ({
+    type: 'Newline',
+    line,
+  }),
+};
+
+module.exports = Node;