hegemonic / catharsis Goto Github PK

It'd be nice to have some performance tests, mostly to prevent significant performance regressions but also because people like benchmarks.

Catharsis currently fails to parse type expressions that contain newline characters.

The fix is easy: Strip newlines before handing them off to the parser.

When JSDoc support is enabled, Catharsis should support type expressions like "foo.bar" and 'foo.bar'. These should be treated as name expressions.

Lodash is looking into using jsdoc and we're running into issues

The type-expression parser doesn't handle nested type unions unless all of the type unions are enclosed in parentheses. So for example this fails:

{Function|...(string|string[])}

but this is ok

{(Function|...(string|string[]))}

Unless the jsdoc option is set, the following code should throw an exception because the type expression null|function is invalid (type unions must be within parentheses):

var catharsis = require('catharsis');

catharsis.parse('null|function()');

As I understand it, this behaviour was introduced in #8.

Ran a Retire.JS scan and it picked out a vulnerability with the version of Jquery that you're using in this module. Would be nice to get it upgraded.

catharsis\node_modules\underscore-contrib\test\vendor\jquery.js
↳ jquery 1.7.2 has known vulnerabilities: severity: medium; bug: 11290, summary: Selector interpreted as HTML; http://bugs.jquery.com/ticket/11290 http://research.insecurelabs.org/jquery/test/ severity: medium; issue: 2432, summary: 3rd party CORS request may execute; jquery/jquery#2432 http://blog.jquery.com/2016/01/08/jquery-2-2-and-1-12-released/

JSDoc supports a @variation tag, which allows you to distinguish between two symbols with the same longname. For example, you might have a Widget namespace and a Widget class; by adding @variation 2 to the class, you can refer to it as {Widget(2)}.

Catharsis needs to allow this when JSDoc support is enabled.

It's gotten a bit out of date.

In other words, make jsdoc: true the default.

Closure Compiler's docs now include a section on generic types, which are defined using the @template tag.

We should implement this tag, using the same semantics as Closure Compiler.

When JSDoc support is enabled, we should be able to parse type expressions like ...[string] (a repeatable, optional parameter that accepts a string).

Closure Compiler now allows type applications that do not contain a period (for example, Array<string> instead of Array.<string>), and it omits the period when converting a type application to a string. See google/closure-compiler#640.

Catharsis currently requires the period unless JSDoc mode is enabled, and it includes the period when converting a type application to a string. Catharsis should be updated to match Closure Compiler.

The current version of PEG.js supports an improved syntax for text nodes. Catharsis should adopt the new syntax, which is clearer and more concise than the old syntax.

Examples of how to use the new syntax: 1, 2, 3, 4, 5.

In some type unions, you need to enclose function types in parentheses to disambiguate the return value (for example, (function(string): boolean)|undefined. We should support this pattern in Catharsis, at least for functions with return values.

Catharsis fails to parse record types such as {0: string}.

This was originally reported as jsdoc/jsdoc#1016.

The type expression {...*} should be parsed as a repeatable parameter that takes any value. Instead, we throw an error. We should fix the error and check whether the "repeatable" literal has problems with other literals.

Originally reported in jsdoc/jsdoc#381.

Like the summary says.

It's a bit silly to do all those checks for process.nextTick and setTimeout, then blindly assume we have access to a Node.js module...

The stringify() method should accept codeClass and codeTag options, just as the describe() method does.

Note to self: Update the buildLink() function in JSDoc once this is done.

The type expression function[] currently throws an error. When JSDoc support is enabled, we should treat this as equivalent to Array.<function()>.

Originally reported in jsdoc/jsdoc#493.

JSDoc needs to be able to stringify bogus type expressions that contain HTML markup, such as:

{
  "type": "TypeApplication",
  "expression": {
    "type": "NameExpression",
    "name": "Array"
  },
  "applications": [
    {
      "type": "NameExpression",
      "name": "<a href=\"FooClass.html\">FooClass</a>"
    }
  ]
}

Without the HTML, that would be stringified as Array.<FooClass>, and I could replace the < with <. With the HTML, though, I need Catharsis to escape the <; otherwise I'll end up escaping the HTML tags as well.

Before I can integrate Catharsis into JSDoc, the parser needs to support a lenient mode that's a little more forgiving than Closure Compiler.

When in lenient mode, the parser should support the following patterns, which have worked in JSDoc 3 for a while:

• Allow function without trailing parens.
• Allow type applications without a period (for example, Array<string>).
• Allow type unions without parens (for example, string|boolean).
• Allow name expressions to contain # and ~, which JSDoc uses to indicate scope. (I think this should only be allowed in lenient mode, although I'm not certain...)

Also, we should maintain separate type caches for lenient-mode and strict-mode parsing.

The parser generated by PEG.js does not provide especially helpful error messages when parsing fails. For example, if you try to parse the type expression Array<string> (should be Array.<string>), the parser throws an exception containing this message:

"$",".",".<","=","\\","\u200C","\u200D","_",Unicode combining mark,Unicode decimal number,Unicode letter number,Unicode lowercase letter,Unicode modifier letter,Unicode other letter,Unicode punctuation connector,Unicode titlecase letter,Unicode uppercase letter

I need to investigate how/whether I can provide better feedback on parse failure.

If you parse a name expression whose name contains special characters (for example, chat."#channel".open), Catharsis throws an error, even though this namepath is perfectly legal.

Need to investigate which characters are legal in property names and make sure we allow all of them.

This issue blocks jsdoc/jsdoc#395.

When JSDoc support is enabled, and you try to parse a type expression like {foo:function()}, you get the following error: Expected "#", ",", ".", "/", ":", "<", "=", "[]", "}" or "~" but "(" found.

When JSDoc support is not enabled, Catharsis has no trouble parsing this type expression.

When describing types, we currently assume that all type applications with a single application are arrays. We should instead use the name of the type expression in this case.

Catharsis needs a way to stringify the parse results back into a Closure Compiler type string. This method should optionally validate the resulting type string by trying to parse it again.

Apparently Catharsis can't deal with nullable values in a type union with missing parentheses. For example, !DoubleRect | !Vector | number results in an error, while DoubleRect | Vector | number and (!DoubleRect | !Vector | number) both work fine.

The missing parentheses are not to spec, but it should be possible to update the grammar so it applies the ! to whatever comes before the next | separator.

This came up on the JSDoc mailing list.

Same syntax as type unions, but with & instead of |.

https://flowtype.org/docs/union-intersection-types.html
https://www.typescriptlang.org/docs/handbook/advanced-types.html

Prerequisite for jsdoc/jsdoc#1285
Related to eslint/doctrine#183

Thanks!

For efficiency, Catharsis caches all of its parse results. Right now it caches all parse results indefinitely, which is not appropriate for a long-running process. Catharsis should use an LRU cache instead.

I think a postfix nullable type operator should be available, because the closure compiler can parse this.

In a library was provided Google, there are many postfix nullable type operators.

/**
 * Sets the parent of this event target to use for bubbling.
 *
 * @param {goog.events.EventTarget?} parent Parent EventTarget (null if none).
 */
goog.events.EventTarget.prototype.setParentEventTarget = function(parent) {
  this.parentEventTarget_ = parent;
};

But, where is an official Closure Compiler type expression specifications...? I have never seen the specifications. The official document is too insufficient.

This makes it a tiny bit easier to read the generated parser code.

Oops!

I found this on stack overflow, but it doesn't work:

  * @param {{name:string, email:string}[]} users

I tried this, and it works:

* @param {Array<{name:String, email:String}>} users

it returns this in applications:

{
  "type": "RecordType",
  "fields": [
    {
      "type": "FieldType",
      "key": {
        "type": "NameExpression",
        "name": "name:String"
      }
    },
    {
      "type": "FieldType",
      "key": {
        "type": "NameExpression",
        "name": "email:String"
      }
    }
}

Is that the recommended way to document nested objects? Or is there something that would further parse the email/string and name/string combinations into their own properties?

EDIT: this stackoverflow answer suggests doing it like this:

* @param {Object[]} users
* @param {string} users[].name - user name
* @param {string} users[].email - user email

Thanks!

Catharsis currently fails on type expressions like foo?=. This form is nonstandard but is used within the Closure Library, and we should be able to parse it.

Trying to parse the type expression integer results in the following exception:

Expected "!", "(", "*", "...", "?", "function", "null", "undefined" or "{" but "i" found.

WTF, Catharsis.

Originally reported as jsdoc/jsdoc#619:

It looks like the parser is being a bit greedy with the undefined literal. I'm getting an error parsing the following comment.

/**
 * @typedef {{className: (string|undefined),
 *     coordinateFormat: (ol.CoordinateFormatType|undefined),
 *     projection: ol.proj.ProjectionLike,
 *     target: (Element|undefined),
 *     undefinedHTML: (string|undefined)}}
 */

Here's the error message:

Invalid type expression "{className: (string|undefined),
   coordinateFormat: (ol.CoordinateFormatType|undefined),
   projection: ol.proj.ProjectionLike,
   target: (Element|undefined),
   undefinedHTML: (string|undefined)}": Expected "!", ",", ":", "=", "?", "|" or "}" but "H" found.

I'm having trouble debugging this. It may be an issue with Catharsis or PEG.js. Thanks for any insight.

Catharsis currently fails to parse type expressions like string[][] (equivalent to Array.<Array.<string>>). We should support this form of nested type application when JSDoc support is enabled.

I'm trying to parse a typedef such as:

@typedef {function((ol.Coordinate|undefined)): string}

which is part of:

/**
 * A function that formats a {@link ol.Coordinate} into a string.
 * @typedef {function((ol.Coordinate|undefined)): string}
 * @todo stability experimental
 */
ol.CoordinateFormatType;

but it seems the function param types and the return type are not available in the JSDoc doclet?

Am I missing something here? Or is this not supported?

The error message refers specifically to the parse() method, but that's no longer the only available method.

Closure Compiler allows type expressions like ...!string (a repeatable, non-nullable string). We need to support these as well.

Originally reported as jsdoc/jsdoc#502.

Catharsis' tests should include some really pathological type expressions, to make sure the grammar doesn't choke on them.

We should also make sure we're testing the parser thoroughly, possibly using node-jscoverage. Here's an example of how to support this.

Might be a pain, since the caches are module-private...

I'm working on a tool that might use jsdoctypeparser but I just noticed this library and saw that it's similar but seems to lean towards closure compiler (is that correct? I'm still getting familiarized with the different specs).

Do you have a recommendation between this and jsdoctypeparser. Will catharsis be used in jsdoc? (just trying to decide which one I should focus on implementing). Thanks!

edit: also, in the returned object, does variable mean "variadic" (e.g. variable number of arguments)? I reviewed the docs and didn't see it (sorry if I missed it).

(Disclaimer: I'll probably never actually do this.)

Catharsis's parser is currently generated by PEG.js from a parsing expression grammar. That seemed like a good choice when I made it. Over time, though, as I've implemented more and more undocumented things that Closure Compiler supports, the grammar has become quite brittle and difficult to change.

In the unlikely event that I'm ever so inclined, it would be interesting to try to reimplement Catharsis as a Pratt parser, which should be more flexible while still being reasonably straightforward to implement by hand.

When JSDoc support is enabled, Catharsis throws an error when it tries to parse the type expression functionWithCallback~callback:

Expected "!", "(", "=", "?", "[]" or "|" but "W" found.

In JSDoc mode, Catharsis throws an error when it parses the type expression ...string|string[]. In contrast, (...string|string[]) is parsed correctly.

When JSDoc support is enabled, we need to allow repeatable function params to omit the square brackets around the param. We also need to allow identifiers to include function signature-like things.

For example, MyClass(...foo) and function(...string) should be allowed only when JSDoc support is enabled; function(...[string]) should always be allowed.

We should allow type expressions like function(...foo) (as opposed to function(...[foo])) whether or not JSDoc support is enabled.

In CommonJS module names it is common to use hyphens.
It is therefore possible for an object to includes a hyphen in the type expression.

Passing module:montage/core/event/event-manager.EventManager to catharsis.parse throws a SyntaxError since the IdentifierName doesn't allow hyphens.

The reason parser doesn't allow hyphens is for numeric value support. I think that we could safely support hyphens in the IdentifierName since I can see no reason to support numeric values in the IdentifierName.

The ticket that describes the usage where this issue is found is here, jsdoc/jsdoc#369