rtl-analyzer 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,37 @@
1
1
  # RTL Analyzer CLI
2
2
 
3
- Standalone CLI packaging for RTL Analyzer. The CLI performs read-only RTL risk scans and can emit JSON, Markdown, structured Markdown, or a self-contained dashboard HTML report.
3
+ RTL Analyzer performs read-only RTL risk scans and can emit JSON, Markdown, structured Markdown, or a self-contained dashboard HTML report.
4
4
 
5
- ## Build and pack
5
+ ## Quick start
6
+
7
+ No global installation is required:
8
+
9
+ ```bash
10
+ npx rtl-analyzer
11
+ ```
12
+
13
+ With no arguments, RTL Analyzer recursively scans the current working directory, writes JSON, Markdown, structured Markdown, and HTML dashboard files to a unique temporary directory outside the project, then opens the dashboard in your default browser. When the dashboard is successfully generated, the CLI prints its path. If the browser cannot be opened, use that printed path instead.
14
+
15
+ On the first run, npm may ask for confirmation before installing the package. Confirm the prompt, or use `npx --yes rtl-analyzer` in scripts and other non-interactive environments.
16
+
17
+ Use `--help` to see the available options:
18
+
19
+ ```bash
20
+ npx rtl-analyzer --help
21
+ npx rtl-analyzer --version
22
+ ```
23
+
24
+ For explicit scans, preserve control over the root, format, and output directory:
25
+
26
+ ```bash
27
+ npx rtl-analyzer scan . --format json
28
+ npx rtl-analyzer scan ./src --format markdown --output-dir ./rtl-report
29
+ npx rtl-analyzer scan . --format dashboard --output-dir ./rtl-report
30
+ ```
31
+
32
+ Options include `--root <path>`, `--format <format>`, `--output-dir <path>`, `--fail-on-findings`, and `--embed-source-snippets` (dashboard output only). Explicit scans do not open a browser automatically.
33
+
34
+ ## Developer build and pack
6
35
 
7
36
  From a fresh checkout, install the repository dependencies, then build and pack the standalone package:
8
37
 
@@ -1,31 +1,97 @@
1
1
  #!/usr/bin/env node
2
- import { readFile } from 'node:fs/promises';
2
+ import { lstat, mkdtemp, readFile, realpath } from 'node:fs/promises';
3
+ import { tmpdir } from 'node:os';
3
4
  import { dirname, join } from 'node:path';
4
5
  import { fileURLToPath } from 'node:url';
6
+ import { spawn } from 'node:child_process';
5
7
  import { runCli } from './cli.js';
6
8
  const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
9
+ const browserLaunchTimeoutMs = 5_000;
7
10
  async function version() {
8
11
  const packageJson = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
9
12
  return packageJson.version ?? '0.0.0';
10
13
  }
11
14
  function help() {
12
- return `RTL Analyzer — conservative RTL risk scanning\n\nUsage:\n rtl-analyzer scan [path] [options]\n rtl-analyzer --help\n rtl-analyzer --version\n\nOptions:\n --root <path> Scan this project root\n --format <format> json, markdown, markdown-structured, or dashboard\n --output-dir <path> Write report artifacts to this directory\n --fail-on-findings Exit 1 when actionable findings exist\n --embed-source-snippets Embed bounded source snippets in dashboard output\n`;
15
+ return `RTL Analyzer — conservative RTL risk scanning\n\nUsage:\n rtl-analyzer Scan the current directory and open a dashboard\n rtl-analyzer scan [path] [options]\n rtl-analyzer --help\n rtl-analyzer --version\n\nOptions:\n --root <path> Scan this project root\n --format <format> json, markdown, markdown-structured, or dashboard\n --output-dir <path> Write report artifacts to this directory\n --fail-on-findings Exit 1 when actionable findings exist\n --embed-source-snippets Embed bounded source snippets in dashboard output\n`;
13
16
  }
14
17
  const io = {
15
18
  writeStdout: value => process.stdout.write(value),
16
19
  writeStderr: value => process.stderr.write(`${value}\n`),
17
20
  };
18
- async function main(argv) {
19
- if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
20
- io.writeStdout(help());
21
+ export function isDirectExecution(invokedPath, modulePath, platform = process.platform) {
22
+ if (!invokedPath || !modulePath)
23
+ return false;
24
+ return platform === 'win32' ? invokedPath.toLowerCase() === modulePath.toLowerCase() : invokedPath === modulePath;
25
+ }
26
+ export async function openDashboard(path, platform = process.platform, launcher = spawn, timeoutMs = browserLaunchTimeoutMs) {
27
+ const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'explorer.exe' : 'xdg-open';
28
+ return new Promise(resolve => {
29
+ let settled = false;
30
+ let timer;
31
+ let child;
32
+ const finish = (opened) => {
33
+ if (settled)
34
+ return;
35
+ settled = true;
36
+ if (timer)
37
+ clearTimeout(timer);
38
+ if (child) {
39
+ child.removeListener('error', onError);
40
+ child.removeListener('close', onClose);
41
+ }
42
+ resolve(opened);
43
+ };
44
+ const onError = () => finish(false);
45
+ const onClose = (code) => finish(code === 0);
46
+ try {
47
+ child = launcher(command, [path], { stdio: 'ignore', shell: false });
48
+ child.once('error', onError);
49
+ child.once('close', onClose);
50
+ timer = setTimeout(() => {
51
+ try {
52
+ child?.kill();
53
+ }
54
+ catch { /* browser process cleanup is best effort */ }
55
+ finish(false);
56
+ }, timeoutMs);
57
+ }
58
+ catch {
59
+ finish(false);
60
+ }
61
+ });
62
+ }
63
+ export async function runDefaultDashboard(options = {}) {
64
+ const outputDir = await mkdtemp(join(await realpath(options.tempRoot ?? tmpdir()), 'rtl-analyzer-dashboard-'));
65
+ const dashboardPath = join(outputDir, 'rtl-report-dashboard.html');
66
+ const output = options.io ?? io;
67
+ const code = await (options.run ?? runCli)(['--root', process.cwd(), '--format', 'dashboard', '--output-dir', outputDir], output);
68
+ let dashboardExists = false;
69
+ try {
70
+ dashboardExists = (await lstat(dashboardPath)).isFile();
71
+ }
72
+ catch { /* report the scan error below */ }
73
+ if (!dashboardExists) {
74
+ output.writeStderr(`Dashboard was not generated: ${dashboardPath}`);
75
+ return code === 0 ? 2 : code;
76
+ }
77
+ output.writeStderr(`Dashboard: ${dashboardPath}`);
78
+ if (!(await (options.open ?? openDashboard)(dashboardPath)))
79
+ output.writeStderr(`Could not open dashboard automatically. Open: ${dashboardPath}`);
80
+ return code;
81
+ }
82
+ export async function main(argv, output = io) {
83
+ if (argv.length === 0)
84
+ return runDefaultDashboard({ io: output });
85
+ if (argv[0] === '--help' || argv[0] === '-h') {
86
+ output.writeStdout(help());
21
87
  return 0;
22
88
  }
23
89
  if (argv[0] === '--version' || argv[0] === '-v') {
24
- io.writeStdout(`${await version()}\n`);
90
+ output.writeStdout(`${await version()}\n`);
25
91
  return 0;
26
92
  }
27
93
  if (argv[0] !== 'scan') {
28
- io.writeStderr(`Unknown command: ${argv[0]}. Use --help for usage.`);
94
+ output.writeStderr(`Unknown command: ${argv[0]}. Use --help for usage.`);
29
95
  return 2;
30
96
  }
31
97
  const scanArgs = argv.slice(1);
@@ -33,6 +99,9 @@ async function main(argv) {
33
99
  if (firstPath && !firstPath.startsWith('-')) {
34
100
  scanArgs.splice(0, 1, '--root', firstPath);
35
101
  }
36
- return runCli(scanArgs, io);
102
+ return runCli(scanArgs, output);
37
103
  }
38
- process.exitCode = await main(process.argv.slice(2));
104
+ const invokedPath = process.argv[1] ? await realpath(process.argv[1]).catch(() => null) : null;
105
+ const modulePath = await realpath(fileURLToPath(import.meta.url)).catch(() => null);
106
+ if (isDirectExecution(invokedPath, modulePath))
107
+ process.exitCode = await main(process.argv.slice(2));
package/package.json CHANGED
@@ -1,7 +1,11 @@
1
1
  {
2
2
  "name": "rtl-analyzer",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Conservative RTL risk scanning and report generation",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "https://github.com/FoushWare/rtl-analyzer.git"
8
+ },
5
9
  "type": "module",
6
10
  "bin": {
7
11
  "rtl-analyzer": "dist/standalone-cli.js"