@efolusi/meridian-guard 1.21.2 → 1.21.4
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 +75 -4
- package/package.json +1 -1
- package/src/cli.mjs +11 -2
- package/src/generated/meridian-rules.json +1 -1
package/README.md
CHANGED
|
@@ -1,24 +1,44 @@
|
|
|
1
1
|
# Meridian Guard
|
|
2
2
|
|
|
3
|
+
Deterministic compliance checks for React applications built with Meridian.
|
|
4
|
+
Guard runs locally, never uploads source, and does not call an AI model.
|
|
5
|
+
|
|
6
|
+
## Requirements and installation
|
|
7
|
+
|
|
8
|
+
Node.js 20.10 or newer is required.
|
|
9
|
+
|
|
3
10
|
Install the public CLI as a development dependency:
|
|
4
11
|
|
|
5
12
|
```sh
|
|
6
13
|
npm install --save-dev @efolusi/meridian-guard
|
|
7
14
|
```
|
|
8
15
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
16
|
+
Add a repeatable project command:
|
|
17
|
+
|
|
18
|
+
```json
|
|
19
|
+
{
|
|
20
|
+
"scripts": {
|
|
21
|
+
"guard": "meridian-guard src"
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Run it with `npm run guard` locally and in CI.
|
|
12
27
|
|
|
13
28
|
## Usage
|
|
14
29
|
|
|
15
30
|
```sh
|
|
16
31
|
npx @efolusi/meridian-guard src
|
|
17
32
|
npx @efolusi/meridian-guard src pages --format json
|
|
33
|
+
npx meridian-guard --help
|
|
18
34
|
```
|
|
19
35
|
|
|
20
36
|
Guard exits `0` when no diagnostics are found, `1` when a contract violation is
|
|
21
|
-
found, and `2` for
|
|
37
|
+
found (including warnings), and `2` for invalid options, missing targets, empty
|
|
38
|
+
scans, or runtime failures. An empty scan fails closed so a misspelled CI target
|
|
39
|
+
cannot silently pass; use `--allow-empty` only when zero source files is expected.
|
|
40
|
+
|
|
41
|
+
Directories are scanned recursively;
|
|
22
42
|
common dependency, framework-output, build, and coverage directories are
|
|
23
43
|
ignored (`node_modules`, `.next`, `.turbo`, `.open-next`, `.wrangler`, `dist`,
|
|
24
44
|
`build`, `coverage`, and their equivalents). Symbolic links are not followed,
|
|
@@ -42,6 +62,57 @@ Dynamic icon names cannot be proven statically and are left to the application.
|
|
|
42
62
|
Guard currently validates Meridian imports from the umbrella package and its
|
|
43
63
|
documented deep-import paths.
|
|
44
64
|
|
|
65
|
+
## Continuous integration
|
|
66
|
+
|
|
67
|
+
GitHub Actions needs no npm token for installing the public package:
|
|
68
|
+
|
|
69
|
+
```yaml
|
|
70
|
+
- uses: actions/setup-node@v5
|
|
71
|
+
with:
|
|
72
|
+
node-version: '22'
|
|
73
|
+
- run: npm ci
|
|
74
|
+
- run: npm run guard
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Use `--format json` when another tool will consume the result. Its stable top-level
|
|
78
|
+
fields are `version`, `filesScanned`, `errors`, `warnings`, and `diagnostics`.
|
|
79
|
+
Every diagnostic includes `file`, `line`, `column`, `ruleId`, `severity`, and
|
|
80
|
+
`message`. The default pretty format is intended for terminal logs:
|
|
81
|
+
|
|
82
|
+
```text
|
|
83
|
+
src/Toolbar.jsx:8:5 error MDG002
|
|
84
|
+
"magnify" is not a Meridian icon. Choose a name from the icon registry.
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Programmatic API
|
|
88
|
+
|
|
89
|
+
The package also exports `guard`, `scanSource`, and the `RULES` metadata:
|
|
90
|
+
|
|
91
|
+
```js
|
|
92
|
+
import { guard } from '@efolusi/meridian-guard';
|
|
93
|
+
|
|
94
|
+
const result = await guard(['src']);
|
|
95
|
+
if (result.diagnostics.length) process.exitCode = 1;
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`scanSource(source, filename, contracts)` is available for editor and test
|
|
99
|
+
integrations that already have source text. Most applications should use the CLI
|
|
100
|
+
or `guard()` so they receive the packaged Meridian contract automatically.
|
|
101
|
+
|
|
102
|
+
## Scope and troubleshooting
|
|
103
|
+
|
|
104
|
+
- Guard parses JavaScript, JSX, TypeScript, TSX, MJS, and CJS. It is a focused
|
|
105
|
+
Meridian contract checker, not a replacement for ESLint or TypeScript.
|
|
106
|
+
- Dynamic component and icon names cannot be proven statically and are skipped.
|
|
107
|
+
- Test/spec files, fixtures, generated output, dependencies, minified files, and
|
|
108
|
+
symbolic links are intentionally skipped. Scan authored application directories.
|
|
109
|
+
- There is no per-rule suppression or configuration file yet. If a diagnostic is
|
|
110
|
+
incorrect, report the smallest reproducible source at the Meridian repository
|
|
111
|
+
instead of hiding the rule globally.
|
|
112
|
+
- Exit `2` usually means the target path is wrong, no supported files were found,
|
|
113
|
+
the source could not be read, or an option is invalid. The CLI prints the exact
|
|
114
|
+
cause to stderr.
|
|
115
|
+
|
|
45
116
|
## Developing
|
|
46
117
|
|
|
47
118
|
The contract at `src/generated/meridian-rules.json` is generated from Meridian's
|
package/package.json
CHANGED
package/src/cli.mjs
CHANGED
|
@@ -5,10 +5,11 @@ import { formatJson, formatPretty } from './reporter.mjs';
|
|
|
5
5
|
const HELP = `Meridian Guard — validate React code against Meridian contracts
|
|
6
6
|
|
|
7
7
|
Usage:
|
|
8
|
-
meridian-guard [path ...] [--format pretty|json]
|
|
8
|
+
meridian-guard [path ...] [--format pretty|json] [--allow-empty]
|
|
9
9
|
|
|
10
10
|
Options:
|
|
11
11
|
--format <name> Output format: pretty (default) or json
|
|
12
|
+
--allow-empty Pass when no supported source files are found
|
|
12
13
|
--help Show this help
|
|
13
14
|
--version Show the Guard rule-pack version
|
|
14
15
|
`;
|
|
@@ -16,10 +17,15 @@ Options:
|
|
|
16
17
|
function parseArgs(argv) {
|
|
17
18
|
const paths = [];
|
|
18
19
|
let format = 'pretty';
|
|
20
|
+
let allowEmpty = false;
|
|
19
21
|
for (let index = 0; index < argv.length; index += 1) {
|
|
20
22
|
const arg = argv[index];
|
|
21
23
|
if (arg === '--help' || arg === '-h') return { help: true, paths, format };
|
|
22
24
|
if (arg === '--version' || arg === '-v') return { version: true, paths, format };
|
|
25
|
+
if (arg === '--allow-empty') {
|
|
26
|
+
allowEmpty = true;
|
|
27
|
+
continue;
|
|
28
|
+
}
|
|
23
29
|
if (arg === '--format') {
|
|
24
30
|
format = argv[index + 1];
|
|
25
31
|
index += 1;
|
|
@@ -33,7 +39,7 @@ function parseArgs(argv) {
|
|
|
33
39
|
paths.push(arg);
|
|
34
40
|
}
|
|
35
41
|
if (!['pretty', 'json'].includes(format)) throw new Error(`unknown format ${format}`);
|
|
36
|
-
return { paths, format };
|
|
42
|
+
return { paths, format, allowEmpty };
|
|
37
43
|
}
|
|
38
44
|
|
|
39
45
|
export async function main(argv, io = process) {
|
|
@@ -50,6 +56,9 @@ export async function main(argv, io = process) {
|
|
|
50
56
|
const cwd = process.cwd();
|
|
51
57
|
const targets = (options.paths.length ? options.paths : ['.']).map(target => path.resolve(cwd, target));
|
|
52
58
|
const result = await guard(targets, { contracts });
|
|
59
|
+
if (result.filesScanned === 0 && !options.allowEmpty) {
|
|
60
|
+
throw new Error('no supported JavaScript or TypeScript source files found; check the target path or pass --allow-empty');
|
|
61
|
+
}
|
|
53
62
|
io.stdout.write(options.format === 'json' ? formatJson(result) : formatPretty(result, cwd));
|
|
54
63
|
if (result.diagnostics.length > 0) io.exitCode = 1;
|
|
55
64
|
}
|