@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 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
- Meridian Guard validates React source against Meridian's component, icon,
10
- token, deprecation, and accessibility contracts. It is deterministic: the CLI
11
- does not upload source or call an AI model.
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 CLI or runtime failures. Directories are scanned recursively;
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@efolusi/meridian-guard",
3
- "version": "1.21.2",
3
+ "version": "1.21.4",
4
4
  "description": "Static compliance checks for React applications built with the Meridian design system.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://meridian.efolusi.com",
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
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "version": "1.21.2",
3
+ "version": "1.21.4",
4
4
  "components": [
5
5
  {
6
6
  "name": "Accordion",