@frozenproductions/niteo 0.1.0 → 0.1.1

package/README.md

@@ -23,13 +23,20 @@ Exact rules, configuration options, and report details are still changing during
 
 ## Installation
 
-After publishing the npm package, run it with `npx`:
+Run directly with `npx`:
 
 ```sh
 npx @frozenproductions/niteo lint
 ```
 
-The npm package builds the Rust binary during installation, so Rust and Cargo must be installed on the machine running `npx`.
+Or install globally and use the `niteo` command:
+
+```sh
+npm i -g @frozenproductions/niteo
+niteo lint
+```
+
+The npm package builds the Rust binary during installation, so Rust and Cargo must be installed on the machine running `npx` or `npm i -g`.
 
 For local development, run it from source:
 
@@ -55,30 +62,52 @@ Scan the default project root:
 
 ```sh
 npx @frozenproductions/niteo lint
+# or, after npm i -g @frozenproductions/niteo
+niteo lint
 ```
 
 Generate a starter config:
 
 ```sh
 npx @frozenproductions/niteo init
+# or
+niteo init
 ```
 
 Scan a specific root:
 
 ```sh
 npx @frozenproductions/niteo lint --root src
+# or
+niteo lint --root src
 ```
 
 Restrict the scan to a path:
 
 ```sh
 npx @frozenproductions/niteo lint --scope src/components
+# or
+niteo lint --scope src/components
+```
+
+Write JSON output to a file:
+
+```sh
+niteo lint --format json --output niteo-report.json
+```
+
+Write SARIF output for code scanning tools:
+
+```sh
+niteo lint --format sarif --output niteo-report.sarif
 ```
 
 Show help:
 
 ```sh
 npx @frozenproductions/niteo --help
+# or
+niteo --help
 ```
 
 ## Configuration
@@ -89,6 +118,8 @@ You can generate a starter config with:
 
 ```sh
 npx @frozenproductions/niteo init
+# or, after npm i -g @frozenproductions/niteo
+niteo init
 ```
 
 The config format is not stable yet, so prefer generating it from the CLI instead of copying old examples.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frozenproductions/niteo",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Standalone Rust CLI for TypeScript structural linting.",
   "license": "MIT",
   "private": false,

package/src/app.rs

@@ -1,9 +1,10 @@
-use anyhow::Result;
+use anyhow::{Context, Result};
 use clap::Parser;
 use std::env;
+use std::fs;
 use std::path::{Path, PathBuf};
 
-use crate::cli::{Cli, Command};
+use crate::cli::{Cli, Command, OutputFormat};
 use crate::{config, discovery, git, report, rules};
 
 pub fn run() -> Result<()> {
@@ -18,6 +19,8 @@ pub fn run() -> Result<()> {
             cli.options.scope,
             cli.options.verbose,
             cli.options.git,
+            cli.options.format,
+            cli.options.output,
         ),
     }
 }
@@ -35,6 +38,8 @@ fn lint_workspace(
     scope_override: Option<PathBuf>,
     verbose: bool,
     git_flag: bool,
+    output_format: OutputFormat,
+    output_path: Option<PathBuf>,
 ) -> Result<()> {
     let project_config = config::ProjectConfig::resolve(workspace, root_override)?;
     let scan_scope = scope_override.map(|scope| resolve_path(workspace, scope));
@@ -103,8 +108,34 @@ fn lint_workspace(
     all_violations.append(&mut depth_violations);
 
     let report = report::Report::new(files, all_violations);
+    let rendered_report = match output_format {
+        OutputFormat::Text => report.render_text(verbose),
+        OutputFormat::Json => report.render_json()?,
+        OutputFormat::Sarif => report.render_sarif()?,
+    };
+
+    write_report(workspace, output_path, &rendered_report)?;
+
+    Ok(())
+}
 
-    println!("{}", report.render_text(verbose));
+fn write_report(
+    workspace: &Path,
+    output_path: Option<PathBuf>,
+    rendered_report: &str,
+) -> Result<()> {
+    let Some(output_path) = output_path else {
+        println!("{rendered_report}");
+        return Ok(());
+    };
+
+    let resolved_output_path = resolve_path(workspace, output_path);
+    if let Some(parent) = resolved_output_path.parent() {
+        fs::create_dir_all(parent)
+            .with_context(|| format!("failed to create {}", parent.display()))?;
+    }
+    fs::write(&resolved_output_path, rendered_report)
+        .with_context(|| format!("failed to write {}", resolved_output_path.display()))?;
 
     Ok(())
 }

package/src/cli.rs

@@ -1,4 +1,4 @@
-use clap::{Args, Parser, Subcommand};
+use clap::{Args, Parser, Subcommand, ValueEnum};
 use std::path::PathBuf;
 
 #[derive(Debug, Parser)]
@@ -32,6 +32,14 @@ pub struct CliOptions {
     /// Scan only changed TypeScript files (skips prompt).
     #[arg(long, global = true)]
     pub git: bool,
+
+    /// Report output format.
+    #[arg(long, global = true, value_enum, default_value_t = OutputFormat::Text)]
+    pub format: OutputFormat,
+
+    /// Write the report to a file instead of stdout.
+    #[arg(short, long, global = true)]
+    pub output: Option<PathBuf>,
 }
 
 #[derive(Debug, Subcommand)]
@@ -41,3 +49,10 @@ pub enum Command {
     /// Scan the project for structural issues.
     Lint,
 }
+
+#[derive(Debug, Clone, Copy, ValueEnum)]
+pub enum OutputFormat {
+    Text,
+    Json,
+    Sarif,
+}

package/src/report.rs

@@ -1,3 +1,5 @@
+use anyhow::Result;
+use serde_json::{Value, json};
 use std::path::PathBuf;
 
 use crate::config::Severity;
@@ -58,6 +60,70 @@ impl Report {
         output
     }
 
+    pub fn render_json(&self) -> Result<String> {
+        let report = json!({
+            "summary": self.summary_json(),
+            "files": self
+                .files
+                .iter()
+                .map(|file| path_to_string(file))
+                .collect::<Vec<String>>(),
+            "violations": self
+                .violations
+                .iter()
+                .map(violation_json)
+                .collect::<Vec<Value>>(),
+        });
+
+        Ok(serde_json::to_string_pretty(&report)?)
+    }
+
+    pub fn render_sarif(&self) -> Result<String> {
+        let rules = group_by_rule(&self.violations)
+            .iter()
+            .map(|group| {
+                json!({
+                    "id": group.rule,
+                    "name": group.rule,
+                    "shortDescription": {
+                        "text": group.message,
+                    },
+                    "defaultConfiguration": {
+                        "level": sarif_level(group.severity),
+                    },
+                })
+            })
+            .collect::<Vec<Value>>();
+
+        let results = self
+            .violations
+            .iter()
+            .map(sarif_result_json)
+            .collect::<Vec<Value>>();
+
+        let report = json!({
+            "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+            "version": "2.1.0",
+            "runs": [
+                {
+                    "tool": {
+                        "driver": {
+                            "name": "Niteo",
+                            "informationUri": "https://github.com/FrozenProductions/Niteo",
+                            "rules": rules,
+                        },
+                    },
+                    "results": results,
+                    "properties": {
+                        "summary": self.summary_json(),
+                    },
+                },
+            ],
+        });
+
+        Ok(serde_json::to_string_pretty(&report)?)
+    }
+
     fn count_by_severity(&self, severity: Severity) -> usize {
         self.violations
             .iter()
@@ -76,6 +142,90 @@ impl Report {
 
         100usize.saturating_sub(penalty)
     }
+
+    fn summary_json(&self) -> Value {
+        let warning_count = self.count_by_severity(Severity::Warn);
+        let error_count = self.count_by_severity(Severity::Error);
+        let info_count = self.count_by_severity(Severity::Info);
+
+        json!({
+            "filesScanned": self.files.len(),
+            "violations": self.violations.len(),
+            "errors": error_count,
+            "warnings": warning_count,
+            "info": info_count,
+            "score": self.score(error_count, warning_count),
+            "status": status_label(error_count, warning_count, info_count),
+        })
+    }
+}
+
+fn violation_json(violation: &Violation) -> Value {
+    json!({
+        "file": path_to_string(&violation.file),
+        "line": violation.line,
+        "column": violation.column,
+        "rule": violation.rule,
+        "message": violation.message,
+        "severity": severity_label(violation.severity),
+        "detail": violation.detail,
+        "subject": violation.subject,
+    })
+}
+
+fn sarif_result_json(violation: &Violation) -> Value {
+    let mut message = violation.message.to_string();
+    if let Some(detail) = &violation.detail {
+        message.push(' ');
+        message.push_str(detail);
+    }
+
+    json!({
+        "ruleId": violation.rule,
+        "level": sarif_level(violation.severity),
+        "message": {
+            "text": message,
+        },
+        "locations": [
+            {
+                "physicalLocation": {
+                    "artifactLocation": {
+                        "uri": path_to_string(&violation.file),
+                    },
+                    "region": {
+                        "startLine": violation.line.unwrap_or(1),
+                        "startColumn": violation.column.unwrap_or(1),
+                    },
+                },
+            },
+        ],
+        "properties": {
+            "severity": severity_label(violation.severity),
+            "subject": violation.subject,
+        },
+    })
+}
+
+fn path_to_string(path: &PathBuf) -> String {
+    path.display().to_string()
+}
+
+fn severity_label(severity: Severity) -> &'static str {
+    match severity {
+        Severity::Error => "error",
+        Severity::Warn => "warning",
+        Severity::Info => "info",
+        Severity::Off => "off",
+    }
+}
+
+fn sarif_level(severity: Severity) -> &'static str {
+    match severity {
+        Severity::Error => "error",
+        Severity::Warn => "warning",
+        Severity::Info => "note",
+        Severity::Off => "none",
+    }
 }
 
 #[derive(Debug)]