jats-cli 0.0.0

package/README.md

@@ -0,0 +1,89 @@
+# jats-cli
+
+[![jats-cli on npm](https://img.shields.io/npm/v/jats-cli.svg)](https://www.npmjs.com/package/jats-cli)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/curvenote/jats-cli/blob/main/LICENSE)
+[![CI](https://github.com/curvenote/jats-cli/workflows/CI/badge.svg)](https://github.com/curvenote/jats-cli/actions)
+
+Node CLI for working with JATS XML documents.
+
+Read, write, and convert JATS XML and log summaries from the command line.
+
+To use from the command line, use the `-g` to create a global install, which will provide a `jats` CLI:
+
+```
+npm install -g jats-xml
+jats -v
+```
+
+## What is JATS?
+
+JATS is a NISO standard for Journal Article Tags Schema, which is a way to define the XML structure of a scientific article semantically. This includes the `front`-matter (authors, funding, title, abstract, etc.), the `body` of the article (sections, figures, equations, tables, etc.), and `back`-matter (references, footnotes, etc.). The JATS can also contain `sub-articles`.
+
+The standard documents are hosted by the NIH <https://jats.nlm.nih.gov/>. There are three flavours, this library currently uses in most cases the most precriptive tag set (for article authoring). Another helpful resource is <https://jats4r.org/>, which provides other examples and recomendations for JATS.
+
+Note that most publishers do **not** provide the XML as a first class output - they should, it is an important part of open-science to have the content programatically accessible and interoperable. It is only [FAIR](https://www.go-fair.org/fair-principles/) 😉.
+
+## From the command line
+
+Commands available:
+
+`download`: attempt to find the JATS file and download it locally.
+
+```bash
+jats download https://elifesciences.org/articles/81952 article.jats
+```
+
+Note, currently this just downloads the XML, **not** the associated files.
+
+`summary`: summarize the contents of the JATS, given a URL, DOI, or local file
+
+```bash
+jats summary https://elifesciences.org/articles/81952
+jats summary 10.1371/journal.pclm.0000068
+jats summary /local/article.jats
+```
+
+This will provide a summary, including a list of what the JATS file contains.
+
+![Output of `jats summary`](/images/jats-output.png)
+
+`validate`: validate local file against JATS Archive DTD schema. By default, this uses JATS 1.3.
+
+```bash
+jats validate article.jats --jats 1.2 --mathmml 2
+```
+
+`test`: test a JATS file against a list of unit tests in YAML
+
+The test cases are useful for known exports and expecting specific pieces of information in the XML.
+
+```bash
+jats test article.jats --cases tests.yml
+```
+
+```yaml
+cases:
+  - title: Correct publisher ID (publisher-id)
+    select: 'front > journal-meta > journal-id[journal-id-type="publisher-id"] > *'
+    equals:
+      type: text
+      value: plos
+  - title: Every orcid is authenticated
+    selectAll: 'front > article-meta > contrib-group > contrib > contrib-id'
+    equals:
+      contrib-id-type: orcid
+      authenticated: 'true'
+```
+
+---
+
+As of v1.0.0 this package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+
+---
+
+<p style="text-align: center; color: #aaa; padding-top: 50px">
+  Made with love by
+  <a href="https://curvenote.com" target="_blank" style="color: #aaa">
+    <img src="https://curvenote.dev/images/icon.png" style="height: 1em" /> Curvenote
+  </a>
+</p>

package/dist/convert.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function addConvertCLI(program: Command): void;
+//# sourceMappingURL=convert.d.ts.map

package/dist/convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAiB5C,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,QAE7C"}

package/dist/convert.js

@@ -0,0 +1,13 @@
+import { Command, Option } from 'commander';
+import { jatsConvert } from 'jats-convert';
+function makeConvertCLI(program) {
+    const command = new Command('convert')
+        .description('Convert JATS file to MyST mdast json')
+        .argument('<input>', 'The JATS file')
+        .addOption(new Option('--frontmatter <frontmatter>', 'Treat JATS frontmatter fields as page or project, or ignore if not specified').choices(['page', 'project']))
+        .action(jatsConvert);
+    return command;
+}
+export function addConvertCLI(program) {
+    program.addCommand(makeConvertCLI(program));
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import version from './version.js';
+import { addDownloadCLI } from './parse.js';
+import { addValidateCLI } from './validate.js';
+import { addTestCLI } from './jats-test.js';
+import { addConvertCLI } from './convert.js';
+const program = new Command();
+addDownloadCLI(program);
+addValidateCLI(program);
+addConvertCLI(program);
+addTestCLI(program);
+program.version(`v${version}`, '-v, --version', 'Print the current version of jats');
+program.option('-d, --debug', 'Log out any errors to the console.');
+program.parse(process.argv);

package/dist/jats-test.d.ts

@@ -0,0 +1,9 @@
+import { Command } from 'commander';
+import type { ISession } from 'jats-xml';
+type Options = {
+    cases: string;
+};
+export declare function testJatsFile(session: ISession, file: string, opts: Options): Promise<boolean>;
+export declare function addTestCLI(program: Command): void;
+export {};
+//# sourceMappingURL=jats-test.d.ts.map

package/dist/jats-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jats-test.d.ts","sourceRoot":"","sources":["../src/jats-test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAU5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,KAAK,OAAO,GAAG;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAsBF,wBAAsB,YAAY,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,oBAsFhF;AAWD,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,QAE1C"}

package/dist/jats-test.js

@@ -0,0 +1,106 @@
+import { Command, Option } from 'commander';
+import { clirun, tic } from 'myst-cli-utils';
+import yaml from 'js-yaml';
+import fs from 'fs';
+import { select, selectAll } from 'unist-util-select';
+import { is } from 'unist-util-is';
+import chalk from 'chalk';
+import { getSession } from 'jats-xml';
+import { parseJats } from './parse.js';
+const INDENT = '       ';
+function printNodes(expected, received) {
+    return chalk.reset(`\n${INDENT}${chalk.greenBright('Expected node containing')}:\n${INDENT}  ${yaml
+        .dump(expected)
+        .replace(/\n/g, `\n${INDENT}  `)}\n${INDENT}${chalk.redBright('Received node')}:\n${INDENT}  ${yaml.dump(received).replace(/\n/g, `\n${INDENT}  `)}`);
+}
+export async function testJatsFile(session, file, opts) {
+    const toc = tic();
+    const jats = await parseJats(session, file);
+    const tests = yaml.load(fs.readFileSync(opts.cases).toString());
+    const results = tests.cases.map((testCase, index) => {
+        if (!testCase.title) {
+            return [`Test Case ${index}`, null, 'Test must include a title'];
+        }
+        if (testCase.equals === undefined) {
+            return [testCase.title, null, 'Test must have an equals statement'];
+        }
+        if (testCase.select) {
+            const node = select(testCase.select, jats.tree);
+            const pass = is(node, testCase.equals);
+            if (testCase.equals == null && node) {
+                return [testCase.title, false, 'Expected no node to be present'];
+            }
+            if (!node && testCase.equals == null)
+                return [testCase.title, true];
+            if (!node)
+                return [testCase.title, false];
+            let failed = false;
+            const messages = [];
+            if (!pass) {
+                failed = failed || true;
+                messages.push(`Failed to validate node\n${printNodes(testCase.equals, node)}`);
+            }
+            return [testCase.title, !failed, messages.join('\n')];
+        }
+        else if (testCase.selectAll) {
+            const testNodes = selectAll(testCase.selectAll, jats.tree);
+            if (!testNodes && testCase.equals == null)
+                return [testCase.title, true];
+            if (!testNodes)
+                return [testCase.title, false, 'Node not found'];
+            let equals = testCase.equals;
+            if (!Array.isArray(testCase.equals)) {
+                equals = Array(testNodes.length).fill(testCase.equals);
+            }
+            let failed = false;
+            const messages = [];
+            if (equals.length !== testNodes.length) {
+                failed = failed || true;
+                messages.push(`Expected ${equals.length} nodes, got ${testNodes.length}\n${printNodes(equals, testNodes)}`);
+            }
+            else {
+                equals.forEach((node, ii) => {
+                    const pass = is(testNodes[ii], node);
+                    if (!pass) {
+                        failed = failed || true;
+                        messages.push(`Failed to validate node ${ii}\n${printNodes(node, testNodes[ii])}`);
+                    }
+                });
+            }
+            return [testCase.title, !failed, messages.join('\n')];
+        }
+        else {
+            return [testCase.title, false, 'Test must have either `select` or `selectAll`'];
+        }
+    });
+    results.forEach((result) => {
+        const [title, pass, message] = result;
+        if (pass === null)
+            session.log.info(`${chalk.redBright.bold(`ERROR`)} - ${title}\n  ${chalk.blueBright(message)}`);
+        else if (pass)
+            session.log.info(`${chalk.green(`PASS`)} - ${title}`);
+        else
+            session.log.info(`${chalk.red(`FAIL`)} - ${title}\n\n${INDENT}${chalk.blueBright(message)}\n`);
+    }, true);
+    const passed = results.reduce((num, [, pass]) => num + (pass ? 1 : 0), 0);
+    const failed = results.length - passed;
+    if (failed > 0 && passed === 0) {
+        throw new Error(toc(`${chalk.red(`Failed ${failed} tests in %s`)} 👎`));
+    }
+    if (failed > 0) {
+        throw new Error(toc(`${chalk.green(`Passed ${passed}/${results.length} tests in %s`)}\n${chalk.red(`Failed ${failed} tests`)} 👎`));
+    }
+    session.log.info(chalk.green(toc(`Passed ${passed} tests in %s 🚀`)));
+    return true;
+}
+function makeTestCLI(program) {
+    const command = new Command('test')
+        .description('Test JATS file against a list of cases')
+        .argument('<file>', 'JATS file to test')
+        .addOption(new Option('--cases <value>', 'The YAML file of unit tests to test against'))
+        .action(clirun(testJatsFile, { program, getSession }));
+    return command;
+}
+export function addTestCLI(program) {
+    program.addCommand(makeTestCLI(program));
+}