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 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?

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.

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.

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

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

We need a matrix of tests for potential transformer chains to ensure they work as expected

json2csv supports "unwinding" headers, so we can represent nested objects (like a report) in CSV output.

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.

it's too common!

show how to make a custom rule and/or transform

A lot of different stuff consumes configs, so I think it makes sense to pull it into common

Since Rule inspection functions can return a Promise, we ought to provide an example of this. currently the builtins are all synchronous.

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)

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

it ain't working.

I think we need rollup-plugin-istanbul

We're doing a bunch of manual overriding of options and this should be done within getOptions() instead.

"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"

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.

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 think if you don't have a config file present, inspect will fail. It should just run all built-in rules by default.

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.

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

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

I'm seeing (no filepath) when the filepath should be known.

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?

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.

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)

HOWTOs on each of the command-line options:

1. inspect
   1. each built-in-rule
   2. single file
   3. multiple files
2. redact
   1. single file
   2. multiple files
3. transform
   1. each built-in transform on a single file
   2. example of combining inspect with transformers
   3. example of combining diff with transformers
4. diff

It needs to provide full API access and the CLI.

Allow color JSON output if supported by terminal

pectin is a tool which provides incremental builds in monorepos.

Investigate if it will work for gnostic and if it's helpful.

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.

a la gnostic-rebase, gnostic-inspect, etc., in addition to the complete gnostic CLI.

This is best accomplished by:

1. breaking up the CLI into multiple "command packages"
2. stuffing common config into its own package
3. using gnostic package as the main CLI, which would depend upon all of the other command packages

This would allow a user to install just gnostic-rebase, for example.

redact needs ability to read a config file and redact against user-supplied regexes.

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.

Ref: https://github.com/hekike/node-report-analytics

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:

1. We can merge any custom options deeply within them, which would otherwise be boilerplate in each transform function
2. Defaults can (in the future) and should be applied via schema validation (ajv). If the merging of options happened within the transform function itself, this would not be possible.
3. When two transformers are chained together, the next transformer pulls in defaults from the previous one. This allows a chain of something like diff -> table to have its output defined by the diff transformer--the table transformer does not and cannot know how to display this data.

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';

Need complete CLI documentation, examples with each option, etc.

looks like we must force-push to it.

I had enabled this because it:

1. restricts imports to a set of whitelisted imports via module-level exports
2. discourages consumers from reaching into the guts of any given package and doing weird stuff

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.

ansi-escapes has an example of providing types and testing those types.

Currently, sorting is done in the core API (toReportFromObject), which doesn't make a lot of sense:

1. sorting must concatenate the stream to an array, which means there's a bottleneck
2. internally, sorting does not matter
3. sorting the output only has any bearing on the order of messages output by the inspector
4. thus, sorting should be done JIT, which would be JUST BEFORE the formatter gets the data
5. and this should happen in the CLI

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

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.

Internationalization for strings

Documentation needs/wants:

• Provide TypeScript definitions
• Provide user API documentation
• Provide plugin author API documentation
• Provide configuration documentation
• Provide HOWTOs:
  • Redact a report running on Cloud Provider X
  • Build a Rule
  • Run as a service
  • Use in browser

Some of these may be absolutely essential, and some are nice-to-have, but there's a list.

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:

1. Command-line flags (if supported)
2. Top-level via RC file
3. Command-specific via RC file
4. Transform-specific via RC file

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.

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.