Git Product home page Git Product logo

dart-shapeshift's Introduction

Shapeshift

Understand how the shape of your Dart package is shifting.

Execute shapeshift against two versions of your Dart docgen-generated API to expose how your API has changed. Shapeshift generates a set of markdown files that list API differences in your Dart package.

Shapeshift can be used as a command-line script, or as Dart library.

The shapeshift.dart script

The shapeshift package comes with a command-line tool, bin/shapeshift.dart. This tool can read JSON-formatted API files (generated by dartdoc), and output, in Markdown format, a list of differences.

Basic example

Assuming you have two versions of your docgen-generated docs at:

/Code/my_package/docs/docs-v1.6.0/
/Code/my_package/docs/docs-v1.7.0/

Then you can run the following command to generate reports of the API differences.

dart bin/shapeshift.dart \
    --base=/Code/my_package/docs \
    --out=./diff-1.6.0_1.7.0 \
    docs-v1.6.0 \
    docs-v1.7.0

In this command, --base specifies the directory where your two documentation directories live. --out specifies a new or existing directory where you want the output markdown files to be written. The final two arguments are the directory with the old and the directory with the new documentation.

This command will create the output directory, if it wasn't there, and write a markdown file for each library that was examined. For example, if a dart-async.json file was found, documenting the dart:async library, then the output will include a dart:async.markdown file.

Each library's markdown file will then include all of the changes found for the library itself, and for every class within the library.

The directory of markdown files works surprisingly well with Jekyll and Jekyll's basic template, but we're working on more streamlined output options.

Options

The shapeshift Dart script accepts the following options:

  • --base is the file path that the two directories (old and new) have in common.
  • --out is an optional directory where the API changes can be written to. Shapeshift will write a separate Markdown file for each library it finds. Each Markdown file will include changes for all member classes of a library. If --out is not used, the differences, still in Markdown format, will be printed to stdout.

Using the Dart library

Shapeshift can also be used with other Dart code as a library. I would recommend importing 'package:shapeshift/shapeshift_common.dart'. The tests can be used as examples.

shapeshift_common library example

Assuming you have two versions of a class's API sitting on disk, say at v1/foo.Foo.json, and v2/foo.Foo.json, you may diff them as follows:

import 'package:shapeshift/shapeshift_common.dart';

void main() {
  String v1 = new File('v1/foo.Foo.json')..readAsStringSync();
  String v2 = new File('v2/foo.Foo.json')..readAsStringSync();

  // Calculate the diff between the two APIs.
  DiffNode diff = diffApis(v1, v2);

  // ReadableStringSink is just a class that acts like a StringSink, but can be
  // read at any point. You can also use a File handle.
  ReadableStringSink io = new ReadableStringSink();

  // The MarkdownWriter takes a callback that will instantiate the write
  // target, if it needs to be written to.
  MarkdownWriter writer = new MarkdownWriter(() => io, false);

  // Create a new ClassReporter for the diff, which can report to the writer.
  // And write!
  new ClassReporter(diff, writer).report();

  // Now io contains the report, in Markdown format.
  print(io.read());
}

shapeshift_common API

TODO: Publish shapeshift as a package, so that it's API is online.

For now, the tests serve as good examples of how to use the API.

License

Apache v2

Contributing

Contributions welcome! Please read the contribution guidelines.

Disclaimer

This is not an official Google product.

dart-shapeshift's People

Contributors

d2m avatar kevmoo avatar pq avatar srawlins avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

dart-shapeshift's Issues

Great tool!

I completely missed the web part of your package, the browser interface / doc_coverage is a great tool!

"Paginate" the version list

It takes crazy long to load the version lists. Particularly the dev one (291 versions last check.) This takes literally > 20 seconds to load. Maybe we just load the most recent 20 versions or something from each channel, and have a button that loads them all.

Support for automating API change detection (a feeler)

I'd love to have a process in my build that verified my current public API against a baseline. I'm imagining a flow like this:

  1. create a baseline
  2. cut a release
  3. hack on code
  4. check changes against baseline and either
    • back out the changes, or
    • update my CHANGELOG and create a new baseline
  5. etc...

As a point of reference on baselines, the olde eclipse API tools come to mind.

Maybe this would be a separate tool?

New method code block comments are... also ugly

When we have a new method, in a diff, we show the method signature, with the method's comment up top. The comment is just a dump of the HTML that exists in the JSON. I wish we could deconstruct the HTML back into the Markdown that generated it.

Wrong subclasses difference

For changes from 1.7.2 to 1.10.1, I had:

class IterableBase

IterableBase has changed subclasses:

  • dart:collection.DoubleLinkedQueue is now dart:collection.DoubleLinkedQueue.

This is the same subclasse, or maybe generics are missing?

unconditionally complains about short descriptions

From a user:

One little thing I noticed was that it unconditionally complains about short descriptions, e.g., 'An dart:mirrors.InstanceMirror reflects an instance of a Dart language object' for InstanceMirror in dart:mirrors. But that sentence is very precise and possibly quite appropriate in the concrete context. Maybe the checks could look up some kind of LGTM for the wording and only complain about completely missing entries? ;-)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.