Skip to content

Commit 3f23488

Browse files
kgrytekgryte
committed
Add utility to list namespace READMEs
1 parent e4b0b3b commit 3f23488

File tree

21 files changed

+2184
-0
lines changed

21 files changed

+2184
-0
lines changed

‎lib/node_modules/@stdlib/_tools/pkgs/namespace-readmes/README.md

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2021 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# Find Namespace READMEs
22+
23+
> Find stdlib namespace package READMEs.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var findREADMEs = require( '@stdlib/_tools/pkgs/namespace-readmes' );
31+
```
32+
33+
#### findREADMEs( \[options,] clbk )
34+
35+
Asynchronously search for namespace package READMEs.
36+
37+
<!-- run-disable -->
38+
39+
```javascript
40+
findREADMEs( onFiles );
41+
42+
function onFiles( error, files ) {
43+
if ( error ) {
44+
throw error;
45+
}
46+
console.log( files.join( '\n' ) );
47+
}
48+
```
49+
50+
The function accepts the following `options`:
51+
52+
- **dir**: root directory from which to search for namespace package READMEs. May be either an absolute path or a path relative to the `stdlib/lib/node_modules/` directory. Default: `/path/to/stdlib/lib/node_modules/`.
53+
- **pattern**: glob pattern used to find namespace packages. Default: `'**/package.json'` (note: pattern **must** end with `package.json`).
54+
- **ignore**: list of glob patterns used to exclude matches.
55+
56+
To search from a descendant directory, set the `dir` option.
57+
58+
```javascript
59+
var opts = {
60+
'dir': './@stdlib/math/base'
61+
};
62+
63+
findREADMEs( opts, onFiles );
64+
65+
function onFiles( error, files ) {
66+
if ( error ) {
67+
throw error;
68+
}
69+
console.log( files.join( '\n' ) );
70+
}
71+
```
72+
73+
To provide an alternative include filter, set the `pattern` option.
74+
75+
```javascript
76+
var opts = {
77+
'pattern': '**/foo/**/package.json'
78+
};
79+
80+
findREADMEs( opts, onFiles );
81+
82+
function onFiles( error, files ) {
83+
if ( error ) {
84+
throw error;
85+
}
86+
console.log( files.join( '\n' ) );
87+
}
88+
```
89+
90+
To exclude matches, set the `ignore` option.
91+
92+
<!-- run-disable -->
93+
94+
```javascript
95+
var opts = {
96+
'ignore': [
97+
'node_modules/**',
98+
'build/**',
99+
'reports/**'
100+
]
101+
};
102+
103+
findREADMEs( opts, onFiles );
104+
105+
function onFiles( error, files ) {
106+
if ( error ) {
107+
throw error;
108+
}
109+
console.log( files.join( '\n' ) );
110+
}
111+
```
112+
113+
#### findREADMEs.sync( \[options] )
114+
115+
Synchronously searches for namespace package READMEs.
116+
117+
<!-- run-disable -->
118+
119+
```javascript
120+
var files = findREADMEs.sync();
121+
// returns [...]
122+
```
123+
124+
The function accepts the same `options` as `findREADMEs()` above.
125+
126+
</section>
127+
128+
<!-- /.usage -->
129+
130+
<section class="notes">
131+
132+
## Notes
133+
134+
- The implementation resolves namespace package READMEs by checking for a `README.md` file in the directory containing a namespace package's `package.json` file.
135+
- Both functions **only** return package READMEs under the `@stdlib` scope.
136+
- Both functions **always** ignore `examples/fixtures`, `test/fixtures`, and `benchmark/fixtures` directories, irrespective of whether an `ignore` option is provided.
137+
- Be **careful** when using the `pattern` option. Both functions first resolve a list of packages matching the search criteria and then prune the list to resolve "namespaces" relative to the resolved list. For example, if the `pattern` option results in resolving only a single package, both functions will always fail to resolve a namespace, regardless as to whether the package actually is a namespace. Only when both functions resolve leaf packages will the functions resolve namespaces.
138+
139+
</section>
140+
141+
<!-- /.notes -->
142+
143+
<section class="examples">
144+
145+
## Examples
146+
147+
<!-- run-disable -->
148+
149+
<!-- eslint no-undef: "error" -->
150+
151+
```javascript
152+
var findREADMEs = require( '@stdlib/_tools/pkgs/namespace-readmes' );
153+
154+
findREADMEs( onFiles );
155+
156+
function onFiles( error, files ) {
157+
if ( error ) {
158+
throw error;
159+
}
160+
console.log( files.join( '\n' ) );
161+
}
162+
```
163+
164+
</section>
165+
166+
<!-- /.examples -->
167+
168+
* * *
169+
170+
<section class="cli">
171+
172+
## CLI
173+
174+
<section class="usage">
175+
176+
### Usage
177+
178+
```text
179+
Usage: stdlib-namespace-readmes [options] [<dir>]
180+
181+
Options:
182+
183+
-h, --help Print this message.
184+
-V, --version Print the package version.
185+
--pattern pattern Inclusion glob pattern.
186+
--ignore pattern Exclusion glob pattern.
187+
```
188+
189+
</section>
190+
191+
<!-- /.usage -->
192+
193+
<section class="notes">
194+
195+
### Notes
196+
197+
- If not provided a `dir` argument, the search directory is the top-level `stdlib` package directory.
198+
199+
- To provide multiple exclusion glob patterns, set multiple `--ignore` option arguments.
200+
201+
<!-- run-disable -->
202+
203+
```bash
204+
$ stdlib-namespace-readmes --ignore=node_modules/** --ignore=build/** --ignore=reports/**
205+
```
206+
207+
</section>
208+
209+
<!-- /.notes -->
210+
211+
<section class="examples">
212+
213+
### Examples
214+
215+
<!-- run-disable -->
216+
217+
```bash
218+
$ stdlib-namespace-readmes
219+
<filepath>
220+
<filepath>
221+
...
222+
```
223+
224+
</section>
225+
226+
<!-- /.examples -->
227+
228+
</section>
229+
230+
<!-- /.cli -->
231+
232+
<section class="links">
233+
234+
</section>
235+
236+
<!-- /.links -->

‎lib/node_modules/@stdlib/_tools/pkgs/namespace-readmes/bin/cli

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
#!/usr/bin/env node
2+
3+
/**
4+
* @license Apache-2.0
5+
*
6+
* Copyright (c) 2021 The Stdlib Authors.
7+
*
8+
* Licensed under the Apache License, Version 2.0 (the "License");
9+
* you may not use this file except in compliance with the License.
10+
* You may obtain a copy of the License at
11+
*
12+
* http://www.apache.org/licenses/LICENSE-2.0
13+
*
14+
* Unless required by applicable law or agreed to in writing, software
15+
* distributed under the License is distributed on an "AS IS" BASIS,
16+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17+
* See the License for the specific language governing permissions and
18+
* limitations under the License.
19+
*/
20+
21+
'use strict';
22+
23+
// MODULES //
24+
25+
var resolve = require( 'path' ).resolve;
26+
var readFileSync = require( '@stdlib/fs/read-file' ).sync;
27+
var CLI = require( '@stdlib/cli/ctor' );
28+
var find = require( './../lib' ); // eslint-disable-line stdlib/no-redeclare
29+
30+
31+
// MAIN //
32+
33+
/**
34+
* Main execution sequence.
35+
*
36+
* @private
37+
*/
38+
function main() {
39+
var flags;
40+
var args;
41+
var opts;
42+
var cli;
43+
44+
// Create a command-line interface:
45+
cli = new CLI({
46+
'pkg': require( './../package.json' ),
47+
'options': require( './../etc/cli_opts.json' ),
48+
'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), {
49+
'encoding': 'utf8'
50+
})
51+
});
52+
53+
// Get any provided command-line options:
54+
flags = cli.flags();
55+
if ( flags.help || flags.version ) {
56+
return;
57+
}
58+
59+
// Get any provided command-line arguments:
60+
args = cli.args();
61+
62+
// Extract options...
63+
opts = {};
64+
if ( flags.pattern ) {
65+
opts.pattern = flags.pattern;
66+
}
67+
if ( flags.ignore ) {
68+
if ( typeof flags.ignore === 'string' ) {
69+
opts.ignore = [ flags.ignore ];
70+
} else {
71+
opts.ignore = flags.ignore;
72+
}
73+
}
74+
if ( args[ 0 ] ) {
75+
opts.dir = args[ 0 ];
76+
}
77+
// Find namespace READMEs:
78+
find( opts, onFiles );
79+
80+
/**
81+
* Callback invoked after finding namespace READMEs.
82+
*
83+
* @private
84+
* @param {(Error|null)} error - error object
85+
* @param {(EmptyArray|StringArray)} files - list of files
86+
* @returns {void}
87+
*/
88+
function onFiles( error, files ) {
89+
if ( error ) {
90+
return cli.error( error );
91+
}
92+
if ( files.length ) {
93+
console.log( files.join( '\n' ) ); // eslint-disable-line no-console
94+
}
95+
}
96+
}
97+
98+
main();

‎lib/node_modules/@stdlib/_tools/pkgs/namespace-readmes/docs/usage.txt

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
2+
Usage: stdlib-namespace-readmes [options] [<dir>]
3+
4+
Options:
5+
6+
-h, --help Print this message.
7+
-V, --version Print the package version.
8+
--pattern pattern Inclusion glob pattern.
9+
--ignore pattern Exclusion glob pattern.
10+

‎lib/node_modules/@stdlib/_tools/pkgs/namespace-readmes/etc/cli_opts.json

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"string": [
3+
"pattern",
4+
"ignore"
5+
],
6+
"boolean": [
7+
"help",
8+
"version"
9+
],
10+
"alias": {
11+
"help": [
12+
"h"
13+
],
14+
"version": [
15+
"V"
16+
]
17+
}
18+
}

‎lib/node_modules/@stdlib/_tools/pkgs/namespace-readmes/examples/index.js

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2021 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
var findREADMEs = require( './../lib' );
22+
23+
findREADMEs( done );
24+
25+
function done( error, files ) {
26+
if ( error ) {
27+
throw error;
28+
}
29+
console.log( files.join( '\n' ) );
30+
}

0 commit comments

Comments
 (0)