Merge pull request #879 from aidarkdev/590

Add `normalize` command.

Author: yegor256

.github/workflows/grunt-old-version.yml

@@ -27,6 +27,11 @@ jobs:
         with:
           distribution: "zulu"
           java-version: ${{ matrix.java }}
+      - name: Install phino
+        run: |
+          curl -fsSL -o phino http://phino.objectionary.com/releases/ubuntu-22.04/phino-latest
+          chmod +x phino
+          sudo mv phino /usr/local/bin/phino
       - run: npm install
       - run: echo '0.59.3' > eo-version.txt
       - run: echo '0.59.3' > home-tag.txt

.github/workflows/grunt.yml

@@ -30,5 +30,23 @@ jobs:
         with:
           distribution: "zulu"
           java-version: ${{ matrix.java }}
+      - name: Install phino (Linux)
+        if: matrix.os == 'ubuntu-24.04'
+        run: |
+          curl -fsSL -o phino http://phino.objectionary.com/releases/ubuntu-22.04/phino-latest
+          chmod +x phino
+          sudo mv phino /usr/local/bin/phino
+      - name: Install phino (macOS)
+        if: matrix.os == 'macos-15'
+        run: |
+          curl -fsSL -o phino http://phino.objectionary.com/releases/macos-15/phino-latest
+          chmod +x phino
+          sudo mv phino /usr/local/bin/phino
+      - name: Install phino (Windows)
+        if: matrix.os == 'windows-2022'
+        run: |
+          Invoke-WebRequest -Uri http://phino.objectionary.com/releases/windows-2022/phino-latest.exe -OutFile phino.exe
+          Move-Item phino.exe C:\Windows\System32\phino.exe
+        shell: powershell
       - run: npm install
       - run: npx grunt

.rultor.yml

@@ -13,6 +13,9 @@ install: |
   pip install git+https://chromium.googlesource.com/external/gyp
   npm install --no-color
   npm install --no-color mocha
+  curl -fsSL -o phino http://phino.objectionary.com/releases/ubuntu-22.04/phino-latest
+  chmod +x phino
+  sudo mv phino /usr/local/bin/phino
   pdd -f /dev/null -v
 release:
   pre: false

README.md

@@ -143,6 +143,9 @@ There are also commands that help manipulate with XMIR and EO sources
 * `docs` generates HTML documentation from `.xmir` files
 * `latex` generates `.tex` files from `.eo` sources
 * `fmt` formats `.eo` files in the source directory
+* `normalize` normalizes `.eo` files via phi-calculus rewriting using
+  [phino](https://github.com/objectionary/phino) (must be installed separately);
+  original files are saved to `.eoc/before-normalize/` for debugging
 * ~~`translate` converts Java/C++/Python/etc. program to EO program~~
 * ~~`demu` removes `cage` and `memory` objects~~
 * ~~`dejump` removes `goto` objects~~

src/commands/docs.js

@@ -8,25 +8,8 @@ const path = require('path');
 const SaxonJS = require('saxon-js');
 const { marked } = require('marked');
 const {elapsed} = require('../elapsed');
+const {findFiles} = require('../files');
 
-/**
- * Recursively reads all .xmir files from a directory.
- * @param {string} dir - Directory path
- * @return {string[]} Array of file paths
- */
-function readXmirsRecursively(dir) {
-  const files = [];
-  const entries = fs.readdirSync(dir, {withFileTypes: true});
-  for (const entry of entries) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...readXmirsRecursively(full));
-    } else if (entry.name.endsWith('.xmir')) {
-      files.push(full);
-    }
-  }
-  return files;
-}
 
 /**
  * Applies XSLT to XMIR
@@ -136,7 +119,7 @@ module.exports = function(opts) {
       fs.writeFileSync(css, '');
       const packages_info = {};
       const all_xmir_htmls = [];
-      const xmirs = readXmirsRecursively(input);
+      const xmirs = findFiles(input, '.xmir');
       for (const xmir of xmirs) {
         const relative = path.relative(input, xmir);
         const name = path.parse(xmir).name;

src/commands/normalize.js

@@ -0,0 +1,64 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2022-2026 Objectionary.com
+ * SPDX-License-Identifier: MIT
+ */
+
+const path = require('path');
+const {execSync} = require('child_process');
+const {mvnw, flags} = require('../mvnw');
+const {elapsed} = require('../elapsed');
+const {findFiles, saveFile, copyDir} = require('../files');
+const relative = require('relative');
+
+/**
+ * Command to normalize .EO files via phi-calculus using phino.
+ * Runs parse, converts XMIR → .phi → normalize → .phi → XMIR → .eo.
+ * Original .eo files are saved to .eoc/before-normalize/ for debugging.
+ * Fails if phino is not installed.
+ * @param {Object} opts - All options
+ * @return {Promise} of normalize task
+ */
+module.exports = function(opts) {
+  if (opts.sources === undefined) {
+    throw new Error('Sources directory is not specified. Please provide it with --sources option.');
+  }
+  if (opts.target === undefined) {
+    throw new Error('Target directory is not specified. Please provide it with --target option.');
+  }
+  try {
+    execSync('phino --version', {stdio: 'pipe'});
+  } catch (e) {
+    throw new Error('phino is not installed, see https://github.com/objectionary/phino', {cause: e});
+  }
+  const sources = path.resolve(opts.sources);
+  const target = path.resolve(opts.target);
+  return elapsed(async (tracked) => {
+    copyDir(sources, path.join(target, 'before-normalize'), '.eo');
+    const parsed = path.join(target, '1-parse');
+    const normed = path.join(target, 'xmir-normalized');
+    const xmirs = findFiles(parsed, '.xmir');
+    console.debug('Found %d XMIR file(s) to normalize', xmirs.length);
+    for (const xmir of xmirs) {
+      const rel = path.relative(parsed, xmir);
+      console.debug('Normalizing %s', rel);
+      const ts = Date.now();
+      const out = execSync(
+        `phino rewrite --input=xmir --output=xmir --normalize ${xmir}`,
+        {stdio: ['pipe', 'pipe', 'pipe']}
+      );
+      console.debug('Normalized in %dms', Date.now() - ts);
+      saveFile(normed, rel, out);
+    }
+    const r = await mvnw(
+      ['eo:print']
+        .concat(flags(opts))
+        .concat([
+          `-Deo.printSourcesDir=${normed}`,
+          `-Deo.printOutputDir=${sources}`,
+        ]),
+      opts.target, opts.batch
+    );
+    tracked.print(`EO files normalized in ${relative(sources)}`);
+    return r;
+  });
+};

src/eoc.js

@@ -33,6 +33,7 @@ const {program} = require('commander'),
     jeo_disassemble: require('./commands/jeo/disassemble'),
     jeo_assemble: require('./commands/jeo/assemble'),
     latex: require('./commands/latex'),
+    normalize: require('./commands/normalize'),
   },
   commands = {
     [language.java]: {
@@ -371,6 +372,15 @@ program.command('latex')
     await coms().latex(program.opts());
   });
 
+program.command('normalize')
+  .description('Normalize EO files using phi-calculus normalization via phino')
+  .action(async (str, opts) => {
+    pin(program.opts());
+    clear(str);
+    await pipe()(coms(), ['register', 'parse'], program.opts());
+    await coms().normalize(program.opts());
+  });
+
 program.command('fmt')
   .description('Format EO files in the source directory')
   .action(async (str, opts) => {

src/files.js

@@ -0,0 +1,61 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2022-2026 Objectionary.com
+ * SPDX-License-Identifier: MIT
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Recursively find all files with given extension in a directory.
+ * @param {string} dir - Directory to search
+ * @param {string} ext - File extension including dot (e.g. '.xmir')
+ * @return {Array.<string>} List of absolute file paths
+ */
+function findFiles(dir, ext) {
+  if (!fs.existsSync(dir)) {return [];}
+  const result = [];
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      result.push(...findFiles(full, ext));
+    } else if (entry.name.endsWith(ext)) {
+      result.push(full);
+    }
+  }
+  return result;
+}
+
+/**
+ * Write content to a file, creating parent directories as needed.
+ * @param {string} dir - Parent directory
+ * @param {string} name - File name relative to dir
+ * @param {Buffer} content - File content
+ */
+function saveFile(dir, name, content) {
+  const file = path.join(dir, name);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, content);
+}
+
+/**
+ * Recursively copy files with given extension from src to dst directory.
+ * @param {string} src - Source directory
+ * @param {string} dst - Destination directory
+ * @param {string} ext - File extension filter (e.g. '.eo'), or empty for all files
+ */
+function copyDir(src, dst, ext) {
+  if (!fs.existsSync(src)) {return;}
+  fs.mkdirSync(dst, {recursive: true});
+  for (const entry of fs.readdirSync(src, {withFileTypes: true})) {
+    const source = path.join(src, entry.name);
+    const dest = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(source, dest, ext);
+    } else if (!ext || entry.name.endsWith(ext)) {
+      fs.copyFileSync(source, dest);
+    }
+  }
+}
+
+module.exports = {findFiles, saveFile, copyDir};

test/commands/test_normalize.js

@@ -0,0 +1,83 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2022-2026 Objectionary.com
+ * SPDX-License-Identifier: MIT
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const {execSync} = require('child_process');
+const {runSync, parserVersion, homeTag, weAreOnline} = require('../helpers');
+
+const eo = '# sample\n[] > simple\n';
+
+function setup(name, content = eo) {
+  const home = path.resolve('temp/test-normalize', name);
+  const source = path.resolve(home, 'src');
+  const target = path.resolve(home, 'target');
+  fs.rmSync(home, {recursive: true, force: true});
+  fs.mkdirSync(source, {recursive: true});
+  fs.mkdirSync(target, {recursive: true});
+  fs.writeFileSync(path.resolve(source, 'simple.eo'), content);
+  runSync([
+    'normalize',
+    '--verbose',
+    `--parser=${parserVersion}`,
+    `--home-tag=${homeTag}`,
+    '-s', source,
+    '-t', target,
+  ]);
+  return {home, source, target};
+}
+
+describe('normalize', () => {
+  before(weAreOnline);
+  before(() => {
+    try {
+      execSync('phino --version', {stdio: 'pipe'});
+    } catch (e) {
+      throw new Error(
+        'phino is required to run normalize tests, see https://github.com/objectionary/phino',
+        {cause: e}
+      );
+    }
+  });
+  it('normalizes EO files and saves originals in before-normalize/', done => {
+    const {source, target} = setup('simple');
+    assert(
+      fs.existsSync(path.resolve(target, 'before-normalize/simple.eo')),
+      'Original .eo file should be saved in before-normalize/'
+    );
+    assert(
+      fs.existsSync(path.resolve(source, 'simple.eo')),
+      'Normalized .eo file should exist in sources directory'
+    );
+    done();
+  });
+  it('normalized output matches expected content', done => {
+    const {source} = setup('content');
+    const actual = fs.readFileSync(path.resolve(source, 'simple.eo'), 'utf8');
+    const expected = '# No comments.\n[] > simple\n';
+    assert.strictEqual(
+      actual, expected,
+      `Normalized output must equal expected.\nExpected:\n${expected}\nActual:\n${actual}`
+    );
+    done();
+  });
+  it('backup matches original input and all pipeline files are produced', done => {
+    const {source, target} = setup('pipeline');
+    const backup = fs.readFileSync(
+      path.resolve(target, 'before-normalize/simple.eo'), 'utf8'
+    );
+    assert.strictEqual(
+      backup, eo,
+      'Backup in before-normalize/ must exactly match the original input'
+    );
+    const xmir = path.resolve(target, 'xmir-normalized/simple.xmir');
+    assert(fs.existsSync(xmir), 'Normalized XMIR file must exist');
+    assert(fs.readFileSync(xmir).length > 0, 'Normalized XMIR file must not be empty');
+    const normalized = fs.readFileSync(path.resolve(source, 'simple.eo'), 'utf8');
+    assert(normalized.length > 0, 'Normalized .eo file must not be empty');
+    done();
+  });
+});