@amritk/mjst 0.9.0 → 0.10.0

package/README.md

@@ -21,6 +21,8 @@
 
 Options can be supplied via CLI flags or a JSON config file. **CLI flags always take precedence over config file values.**
 
+It also carries a `lint` subcommand — `mjst lint <files>` — a format-agnostic JSON/YAML style-guide linter powered by [`@amritk/lint`](../lint). See [Linting](#linting).
+
 ---
 
 ## Installation
@@ -116,6 +118,45 @@ npx mjst --config ./mjst.config.json
 
 ---
 
+## Linting
+
+`mjst lint` lints JSON/YAML documents against a ruleset — JSON Schema validation and custom style rules, with exact `line:column` findings. It has its own flags (and its own `--help`), independent of the generation flags above.
+
+```bash
+# Lint files against an explicit ruleset
+npx mjst lint "**/*.{yaml,json}" -r .lint.yaml
+
+# Auto-discover a .lint.* ruleset by walking up from each file
+npx mjst lint config/
+
+# Lint piped input
+cat service.yaml | npx mjst lint --stdin-filepath service.yaml
+```
+
+Findings are printed as a compact, editor-clickable report:
+
+```
+config/service.yaml:2:7  error  config-schema  /port must be integer
+
+✖ 1 problem(s) (1 error(s), 0 warning(s))
+```
+
+With no `-r`, mjst discovers a `.lint.{yaml,yml,json,js,mjs}` ruleset by walking up from each linted file. A ruleset maps a JSONPath (`given`) to a function (`then`) — `schema` (JSON Schema), `casing`, `pattern`, `truthy`, and more, plus your own. The [`@amritk/lint` README](../lint#ruleset-format) documents the ruleset format and built-in functions. For machine-readable output (JSON, SARIF, …), call the [`@amritk/lint`](../lint) library's `lintDocument`, which returns structured findings.
+
+| Flag | Description |
+| --- | --- |
+| `<documents..>` | Files or globs to lint (positional). |
+| `-r`, `--ruleset` | Path to a ruleset file. Defaults to `.lint.*` discovery. |
+| `-F`, `--fail-severity` | Minimum severity that fails the run: `error` (default), `warn`, `info`, `hint`. |
+| `-D`, `--display-only-failures` | Only show findings at or above `--fail-severity`. |
+| `--stdin-filepath` | Path to associate with piped input (labels findings and enables ruleset discovery). |
+| `--concurrency` | Max documents linted in parallel (default `8`). |
+| `-q`, `--quiet` | Suppress the findings report (the exit code still reflects findings). |
+
+The exit code is `0` when no finding reaches `--fail-severity`, `1` when one does, and `2` on a usage error. Run `mjst lint --help` for the full list.
+
+---
+
 ## Configuration reference
 
 <!-- config-table-start -->

package/dist/cli.js

@@ -249,6 +249,18 @@ const runRecursive = async (config, schemaDir, outputDir) => {
 const run = async () => {
     // Skip the first two args (node executable and script path)
     const args = process.argv.slice(2);
+    // `mjst lint <files>` delegates to the linter, which owns its own flag parsing
+    // and `--help` (yargs) — so this must run before the shared version/help checks,
+    // otherwise `mjst lint --help` would print the codegen help instead.
+    if (args[0] === 'lint') {
+        const { run: lintRun } = await import('./lint/run.js');
+        const result = await lintRun(args.slice(1));
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        process.exit(result.code);
+    }
     if (isVersionRequest(args)) {
         console.log(await readVersion());
         return;

package/dist/lint/ruleset-loader.d.ts

@@ -0,0 +1,5 @@
+import { type RulesetDefinition } from '@amritk/lint';
+/** Loads a ruleset definition from a YAML, JSON, or JS/MJS file. */
+export declare const loadRuleset: (path: string) => Promise<RulesetDefinition>;
+/** Walks up from a directory looking for a `.lint.*` ruleset file. */
+export declare const discoverRuleset: (startDir: string) => string | undefined;

package/dist/lint/ruleset-loader.js

@@ -0,0 +1,31 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseWithPointers } from '@amritk/lint';
+const RULESET_FILENAMES = ['.lint.yaml', '.lint.yml', '.lint.json', '.lint.js', '.lint.mjs'];
+/** Loads a ruleset definition from a YAML, JSON, or JS/MJS file. */
+export const loadRuleset = async (path) => {
+    const absolute = isAbsolute(path) ? path : resolve(process.cwd(), path);
+    if (/\.(c|m)?js$/.test(absolute)) {
+        const module = await import(pathToFileURL(absolute).href);
+        return (module.default ?? module);
+    }
+    const content = await readFile(absolute, 'utf8');
+    return parseWithPointers(content).data;
+};
+/** Walks up from a directory looking for a `.lint.*` ruleset file. */
+export const discoverRuleset = (startDir) => {
+    let dir = resolve(startDir);
+    while (true) {
+        for (const name of RULESET_FILENAMES) {
+            const candidate = join(dir, name);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+};

package/dist/lint/run.d.ts

@@ -0,0 +1,15 @@
+/** The outcome of a {@link run}: exit code plus the text it would print. */
+export type RunResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * Runs the linter over `argv`, returning the exit code and the text it would
+ * print (rather than writing to the process streams) so it can be driven
+ * in-process by tests. `stdin` supplies the piped document when there are no file
+ * targets; when omitted it is read from `process.stdin`.
+ */
+export declare const run: (argv: string[], options?: {
+    stdin?: string;
+}) => Promise<RunResult>;

package/dist/lint/run.js

@@ -0,0 +1,176 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { DiagnosticSeverity, lintDocument, validateRuleset, } from '@amritk/lint';
+import fg from 'fast-glob';
+import yargs from 'yargs';
+import { discoverRuleset, loadRuleset } from './ruleset-loader.js';
+const SEVERITY_BY_NAME = {
+    error: DiagnosticSeverity.Error,
+    warn: DiagnosticSeverity.Warning,
+    info: DiagnosticSeverity.Information,
+    hint: DiagnosticSeverity.Hint,
+};
+const SEVERITY_LABEL = ['error', 'warning', 'info', 'hint'];
+/**
+ * Renders findings as a compact, dependency-free report — one `file:line:col`
+ * line per finding (1-based, editor-clickable), then a count summary. Structured
+ * output (JSON, SARIF, …) is a consumer concern: use the `@amritk/lint` library's
+ * `lintDocument`, which returns `IDiagnostic[]`.
+ */
+const formatReport = (findings) => {
+    if (findings.length === 0)
+        return 'No problems found\n';
+    const lines = findings.map((d) => {
+        const loc = `${d.source ?? '<stdin>'}:${d.range.start.line + 1}:${d.range.start.character + 1}`;
+        return `${loc}  ${SEVERITY_LABEL[d.severity] ?? 'error'}  ${d.code}  ${d.message}`;
+    });
+    const errors = findings.filter((d) => d.severity === DiagnosticSeverity.Error).length;
+    const warnings = findings.filter((d) => d.severity === DiagnosticSeverity.Warning).length;
+    lines.push('', `✖ ${findings.length} problem(s) (${errors} error(s), ${warnings} warning(s))`);
+    return `${lines.join('\n')}\n`;
+};
+const readStdin = async () => {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+};
+const filterBySeverity = (results, failSeverity) => results.filter((result) => result.severity <= failSeverity);
+/**
+ * Maps `items` through `worker` with at most `limit` running at once, preserving
+ * input order in the result. Lets the CLI lint a directory of documents
+ * concurrently instead of strictly one at a time, without unbounded parallelism.
+ */
+const mapWithConcurrency = async (items, limit, worker) => {
+    const results = new Array(items.length);
+    let next = 0;
+    const runners = new Array(Math.max(1, Math.min(limit, items.length))).fill(0).map(async () => {
+        while (true) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            results[index] = await worker(items[index]);
+        }
+    });
+    await Promise.all(runners);
+    return results;
+};
+/**
+ * Runs the linter over `argv`, returning the exit code and the text it would
+ * print (rather than writing to the process streams) so it can be driven
+ * in-process by tests. `stdin` supplies the piped document when there are no file
+ * targets; when omitted it is read from `process.stdin`.
+ */
+export const run = async (argv, options = {}) => {
+    const out = [];
+    const err = [];
+    const parsed = (await yargs(argv)
+        .scriptName('lint')
+        .parserConfiguration({ 'greedy-arrays': false })
+        .usage('$0 [documents..]', 'Lint JSON/YAML documents against a ruleset')
+        .positional('documents', { describe: 'Documents or globs to lint', type: 'string', array: true })
+        .option('ruleset', { alias: 'r', type: 'string', describe: 'Path to a ruleset file' })
+        .option('encoding', { type: 'string', default: 'utf8', describe: 'Input encoding' })
+        .option('fail-severity', { alias: 'F', type: 'string', default: 'error', choices: Object.keys(SEVERITY_BY_NAME) })
+        .option('display-only-failures', { alias: 'D', type: 'boolean', default: false })
+        .option('verbose', { type: 'boolean', default: false })
+        .option('quiet', { alias: 'q', type: 'boolean', default: false })
+        .option('stdin-filepath', {
+        type: 'string',
+        describe: 'Path to associate with stdin input (labels findings and enables ruleset discovery)',
+    })
+        .option('concurrency', {
+        type: 'number',
+        default: 8,
+        describe: 'Maximum number of documents to lint in parallel',
+    })
+        .help()
+        .alias('help', 'h')
+        .parse());
+    const failSeverity = SEVERITY_BY_NAME[parsed.failSeverity] ?? DiagnosticSeverity.Error;
+    const reportRulesetProblems = (definition, label) => {
+        if (parsed.quiet)
+            return;
+        for (const problem of validateRuleset(definition)) {
+            const at = problem.path.length > 0 ? ` (at ${problem.path.join('.')})` : '';
+            err.push(`warning: ruleset ${label}: ${problem.message}${at}\n`);
+        }
+    };
+    const discoverAndLoad = async (dir) => {
+        const discovered = discoverRuleset(dir);
+        if (!discovered)
+            return undefined;
+        const definition = await loadRuleset(discovered);
+        reportRulesetProblems(definition, discovered);
+        return { definition, basePath: dirname(discovered) };
+    };
+    let rulesetDefinition;
+    let rulesetBasePath;
+    if (parsed.ruleset) {
+        rulesetDefinition = await loadRuleset(parsed.ruleset);
+        rulesetBasePath = dirname(isAbsolute(parsed.ruleset) ? parsed.ruleset : resolve(process.cwd(), parsed.ruleset));
+        reportRulesetProblems(rulesetDefinition, parsed.ruleset);
+    }
+    const targets = await fg(parsed.documents ?? [], { dot: true, onlyFiles: true });
+    const allResults = [];
+    if (targets.length === 0) {
+        if (options.stdin === undefined && process.stdin.isTTY) {
+            return { code: 2, stdout: '', stderr: 'No documents provided.\n' };
+        }
+        const content = options.stdin ?? (await readStdin());
+        // With --stdin-filepath, label findings with that path and discover a
+        // `.lint.*` ruleset by walking up from its directory.
+        const stdinPath = parsed.stdinFilepath;
+        let definition = rulesetDefinition;
+        let basePath = rulesetBasePath;
+        if (!definition && !parsed.ruleset && stdinPath) {
+            const discovered = await discoverAndLoad(dirname(stdinPath));
+            if (discovered)
+                ({ definition, basePath } = discovered);
+        }
+        const opts = {
+            ...(definition ? { ruleset: definition } : {}),
+            ...(basePath !== undefined ? { rulesetBasePath: basePath } : {}),
+            source: stdinPath ?? '<stdin>',
+        };
+        allResults.push(...(await lintDocument(content, opts)));
+    }
+    else {
+        // Cache discovered/loaded rulesets by directory so a directory of documents
+        // that share a `.lint.*` file parses it once, not once per file.
+        const rulesetCache = new Map();
+        const perFile = await mapWithConcurrency(targets, parsed.concurrency, async (file) => {
+            const content = await readFile(file, parsed.encoding);
+            let definition = rulesetDefinition;
+            let basePath = rulesetBasePath;
+            if (!definition && !parsed.ruleset) {
+                const dir = dirname(file);
+                let discovered = rulesetCache.get(dir);
+                if (!rulesetCache.has(dir)) {
+                    discovered = await discoverAndLoad(dir);
+                    rulesetCache.set(dir, discovered);
+                }
+                if (discovered)
+                    ({ definition, basePath } = discovered);
+            }
+            const opts = definition
+                ? {
+                    ruleset: definition,
+                    ...(basePath !== undefined ? { rulesetBasePath: basePath } : {}),
+                    source: file,
+                }
+                : { source: file };
+            return lintDocument(content, opts);
+        });
+        for (const remaining of perFile)
+            allResults.push(...remaining);
+    }
+    const displayed = parsed.displayOnlyFailures ? filterBySeverity(allResults, failSeverity) : allResults;
+    if (!parsed.quiet)
+        out.push(formatReport(displayed));
+    return {
+        code: filterBySeverity(allResults, failSeverity).length > 0 ? 1 : 0,
+        stdout: out.join(''),
+        stderr: err.join(''),
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/mjst",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "type": "module",
   "license": "MIT",
@@ -44,9 +44,13 @@
     "@amritk/adapters": "0.2.16",
     "@amritk/generate-parsers": "0.15.0",
     "@amritk/generate-markdown": "0.4.1",
-    "@amritk/helpers": "0.12.0"
+    "@amritk/helpers": "0.12.0",
+    "@amritk/lint": "0.1.0",
+    "fast-glob": "^3.3.2",
+    "yargs": "^17.7.2"
   },
   "devDependencies": {
-    "json-schema-typed": "^8.0.1"
+    "json-schema-typed": "^8.0.1",
+    "@types/yargs": "^17.0.33"
   }
 }