ibm / report-toolkit Goto Github PK
View Code? Open in Web Editor NEWA toolkit for consumers of Node.js diagnostic Reports
Home Page: https://ibm.github.io/report-toolkit
License: Other
A toolkit for consumers of Node.js diagnostic Reports
Home Page: https://ibm.github.io/report-toolkit
License: Other
Currently, we're sending whole gobs of configuration to transformers when we don't need to. Each transformer should probably define the options that it expects (e.g. via a schema like Rules support), and we can use that to pick the various useful options.
Configuration can be passed via:
Furthermore, default options should cascade within a transformer chain. If an option defines e.g., fields
, and the user has not, this setting should pass to the next transformer(s) in the chain as long as those transformers accept the configuration. The target transformer should prefer the config sent from the previous transformer and treat it like it was user-defined.
These are unit tests, but the transform
function that each exports is only ever called by the Transformer
class, which applies any default options defined within a transformer. Calling these functions directly does not apply those defaults.
The reasoning behind defining defaults in the meta
object is threefold:
transform
functionajv
). If the merging of options happened within the transform
function itself, this would not be possible.diff
-> table
to have its output defined by the diff
transformer--the table
transformer does not and cannot know how to display this data.Add an ESLint rule that bans use of _
exported from @gnostic/common
.
These are aimed to be good examples for users to write their own rules, and as such, we don't want to depend on 3p libs.
I'm seeing (no filepath)
when the filepath should be known.
We may be able to rename this project back at some point (assuming future approval), but for now, it must be report-toolkit
before it goes public.
wherever possible, use the field labels instead of properties in the json transformer
list-rules
command should have keys rule
and description
, not id
and description
.
(note that the keys should be normalized to lower case)
It needs to provide full API access and the CLI.
I had enabled this because it:
But it's plainly inconvenient:
import {observable} from '@report-toolkit/common';
const {all, the, stuff, I, need, to, use} = observable;
where it'd be nicer to just:
import {all, the, stuff, I, need, to, use} from '@report-toolkit/common/observable';
Now, each package puts everything in 'src/', so we'd want to actually move the files out of there and into the package root.
This same thing should be possible when using the CJS bundle. I'm not sure the best way to accomplish that, but I think we can look at RxJS as an example, because I believe it allows this. It doesn't bundle itself for CJS, however (it just compiles via TypeScript), which means our Rollup configuration may be limited to generating UMD bundles for browser use. We could then just use @babel/cli
to transpile for CJS.
the user should be able to use multiple transformers (in order).
this might get a little complex, because transformers expect a Report
as input. this is starting to look like readable/writable streams a bit, where you can't read the output of a writable stream, unless it's a transform stream.
not that I'm not advocating for use of Node.js streams, as the horror of working with them is the reason I'm using observables
We have some functions in @report-toolkit/fs
that are presently not used. This is due, in part, to bundling a CJS module.
At present, only built-in Rules are accessible via the inspect
CLI command. This is a bug. We need to be able to load third-party rules via require()
, at minimum.
Ensure the present functionality supports this (see fs-rule-loader.js
), and write tests.
I was operating under the definition that a formatter took a raw report and returned it in some specific output format, and a transformer took a raw report and output some other shape of data, and was intended to be piped through to a formatter.
But, the original transformer (numeric
) was intended to essentially filter (and restructure) a report--and it can only really be used with the pipe
formatter. It doesn't really make sense to use the pipe
formatter outside of the numeric
context unless you wanted to consume it via something like a newline-delimited readable stream.
anyhow... I'm thinking perhaps we don't need to differentiate between formatters and transformers. indeed it makes things more complex for the user. not sure.
perhaps some of these combinations could be shortcuts or prerolled configurations.
UPDATE: I've done some work here on the transformers, but there's work to re-integrate them into some of the commands:
list-rules
inspect
diff
The public APIs should be consistent and minimal, and there should be feature-parity between the Observable-based API and Promise-based API.
Polish this up before initial release
Since Rule inspection functions can return a Promise, we ought to provide an example of this. currently the builtins are all synchronous.
it ain't working.
I think we need rollup-plugin-istanbul
looks like we must force-push to it.
Allow color JSON output if supported by terminal
I'm not sure of the best way to distribute these. Right now, it just stuffs all dependencies into the resulting bundle, which is not optimal.
Maybe we shouldn't worry about it, because any consuming app will use ES modules and do its own tree-shaking & bundling?
Maybe this is something like a "wizard".
Developers may need to analyze reports but don't know exactly what they need; rather they know something bad is happening. At minimum they might know that e.g., "the process is running out of memory." we want to create optimized solutions to specific problems.
Provide some way for a user to describe a problem (perhaps from a list of options), then rtk will use its facilities to help solve the issue. this might involve generating a reusable configuration which can then be subsequently applied to more reports, or maybe it's configs alongside the rtk:recommended
config. (note: rtk:recommended
might not be useful)
The rules
pkg should ideally be completely transparent to the CLI. core
should handle whatever the CLI is doing directly with the rules.
This is a bug (I think). It looks like we're pulling the wrong data out of the config files. You should be able to set e.g., pretty: true
in an RC file and have that reflected when running on CLI
it's too common!
Currently, sorting is done in the core API (toReportFromObject
), which doesn't make a lot of sense:
ansi-escapes has an example of providing types and testing those types.
a la gnostic-rebase
, gnostic-inspect
, etc., in addition to the complete gnostic
CLI.
This is best accomplished by:
gnostic
package as the main CLI, which would depend upon all of the other command packagesThis would allow a user to install just gnostic-rebase
, for example.
We need a matrix of tests for potential transformer chains to ensure they work as expected
This is a regression introduced after #9.
We need some way to declare a secret which can be a key or value, but only within a "subtree" of the report.
pectin is a tool which provides incremental builds in monorepos.
Investigate if it will work for gnostic and if it's helpful.
Various packages have constants in them, and they should all export these in a similar shape.
It's absolutely useful to be able to iterate over a set of constants exported from a package. For example, names of formatters or transformers. If a package has a single entry point, then constants-as-named-exports won't get us there, because those exports may not all be constants!
I'm thinking this should be sufficient:
/**
* @enum {string}
*/
export const constants = {
FOO: 'foo',
BAR: 'bar',
BAZ: 'baz'
};
A consumer can:
import {constants as fooConstants} from '@report-toolkit/foo';
Documentation needs/wants:
Some of these may be absolutely essential, and some are nice-to-have, but there's a list.
Currently, the CLI imports @report-toolkit/transformers
directly, and it should not--it should only interact with @report-toolkit/core
. Abstract the current functionality it's using in core.
We want browser support in every package which does not do Node.js-specific stuff (essentially, everything except @gnostic/cli
and @gnostic/fs
).
Rollup seems like an obvious choice, since most packages are intended to be used as libraries.
It may make sense to use Rollup in the above two modules for consistency, but it's of less importance.
A lot of different stuff consumes configs, so I think it makes sense to pull it into common
Need complete CLI documentation, examples with each option, etc.
I'm not sure of the interaction between standard-version and lerna, but if it works, I'd like to use it.
It's not possible to use standard-version with Lerna, but you can apparently coax Lerna into doing something very similar.
Investigate and implement. We want to have automatic changelog generation based on conventional commits.
this means that @report-toolkit/transformers
should be a plugin.
plugins should not only allow for rule defs, but transformer defs as well.
update #51 to reflect this change
investigate https://gatsby-theme-carbon.now.sh/getting-started/
I want to use the Carbon Design System for the site, but I'm not sure of the easiest way from point A to B for our purposes. this might be it.
HOWTOs on each of the command-line options:
inspect
redact
transform
inspect
with transformersdiff
with transformersdiff
redact needs ability to read a config file and redact against user-supplied regexes.
"The configuration stuff could be some of the worst code I've ever
written. There's more refactoring to be done here; we should load the
transformers first using defaults & user-supplied configuration, THEN
we should validate the chain. Right now we're trying to do both at once
which is just vile"
I think if you don't have a config file present, inspect
will fail. It should just run all built-in rules by default.
Looks like the terminal widths aren't stretching how they should across various commands
Might also want to refactor this, because it should work w/o having to manually pass maxWidth
, etc.
Internationalization for strings
json2csv supports "unwinding" headers, so we can represent nested objects (like a report) in CSV output.
show how to make a custom rule and/or transform
one use case for gnostic is post-mortem debugging. when analyzing stacktraces from a crashed process, it's useful to know if a particular exception thrown is unique. we can determine the uniqueness of any given traceback by removing variable information and distilling to the list of lines in the stack itself, then taking a hash of the result.
provide a command which accepts a report and outputs a hash of the stack trace.
We're doing a bunch of manual overriding of options and this should be done within getOptions()
instead.
The way we pull command-specific configuration out of the config is tedious. a Config class with a helper method or two would make this easier to digest.
also, it could help define the (post-normalization) interface.
This is a general-purpose transformer which will "pick" fields from the report.
Allow use of keypaths (foo.bar.baz
).
This is likely most useful when combined with another transformer, but it doesn't need to be used this way
This is an edge case, but what should we do if a Rule returns more than one equivalent message? This is ostensibly going to be a bug in the Rule implementation, but is there a use-case for this? Should we just silently dedupe, or throw an exception, something else?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.