v1.0.0 (#1145)

* Use parse5 as a default parser (closes #863)

* Use documents via $.load

* Add test for #997

* Change options format

* Update unit test

Update test phrasing according to recent changes in parsing logic.

* 1.0.0-rc.1

* Improve release process

Limit responsibility of "pre-publish" script to simply validate the
project's `History.md` file (by verifying an entry for the current
release). Define a separate script for history generation. Separating
the workflow in this way allows for manual modification of the release
notes.

* Correct errors in Readme.md

* Document advanced usage with htmlparser2

* Update History.md (and include migration guide)

* Remove documentation for `xmlMode` option

Simply expose an option named `xml` that enables XML parsing via
htmlparser2 with the ability to specify additional options for that
parser.

* Rename `useHtmlParser2` option

This flag is used to control parsing behavior internally, but it is not
intended for use by consumers. Prefix the name with an underscore in
order to discourage users from relying on it.

* Re-write migration guide for version 1.0 (#1078)

Incorporate recent feedback from consumers who have experimented with
the version 1.0 release candidate.

* Pass locationInfo option to parse5 (#1155)

* Update css-select to the latest version 🚀 (#1158)

Breaking change: Invalid selectors now throw Errors, not SyntaxErrors.

* Use eslint & prettier, add precommit hook (#1152)

* chore(package): update mocha to version 5.0.4 (#1088)

* Ensure text nodes expose the DOM level 1 API

Since enabling the `withDomLvl1` parsing option, nodes cannot be created
with an object literal. Create new text nodes using the `evaluate`
function to ensure they expose the correct attributes.

* fixing missing prop(‘outerHTML’) implementation.
Added an ‘outerHTML’ case to the switch in the prop function, which wraps a clone of  in a container element, and sets  to that container's HTML (#945)

* Do not lint files excluded from version control (#1162)

This includes code coverage reports as generated by the command `make
test-cov`.

* Correct typo in git hook configuration (#1163)

* Correct typo in git hook configuration

* Reformat package manifest to satisfy linter

* Fix .text with a function as the argument

* Fix `.text` being called on a collection with size > 1 with a function

* chore(package): update coveralls to version 3.0.0 (#1086)

* Update jsdom to the latest version 🚀 (#1008)

* Throw a useful error on invalid input to cheerio.load() (#1087)

* Procedurally generate API documentation from source (#1165)

* Use parse5 to serialize the DOM, use lodash to clone dom

* Fix DoS/RCE vulnerability in lodash@4.15.0 (#1179)

fixes #1175

*  Add eslint-plugin-jsdoc, improve documentation (#1168)

* Improve variable names (#1183)

Promote consistency in variable names within the project's source and
unit tests. This helps to highlight the distinction between the object
exported by the module and the function produced by the `load` method.
The latter value is expected to mimic the jQuery API, while the former
value generally should only be used for a small set of methods specific
to Cheerio:

- `load`
- `html`
- `xml`
- `text`

Other usages of the exported object are discouraged, and a future patch
will update the unit tests to reflect the usages that are endorsed for
long-term stability.

* Formally test deprecated APIs (#1184)

Methods named `load`, `html`, `xml`, and `text` are defined in many
locations:

Today, Cheerio defines multiple versions of methods named `load`,
`html`, `xml`, `text`, and `parseHTML`. These alternate versions may be
defined in up to three distinct parts of the API:

- exported by the Cheerio module
- as static methods of the "loaded" Cheerio factory function
- as instance methods of the "loaded" Cheerio factory function

Some of these are surperfluous, and because some unecessarily conflict
with idiomatic jQuery coding patterns, they have been designated for
future removal [1].

Add tests for the deprecated methods in order to avoid regressions prior
to their removal. Insert comments to delineate the methods which are
endorsed and which have been deprecated. For the latter group of
methods, include recommendation for the preferred alternatives.

[1] #1122

* Implement for...of iterator via Symbol.iterator (#1197)

* Implement for...of iterator via Symbol.iterator

Similar to jQuery: https://github.com/jquery/jquery/blob/1ea092a54b00aa4d902f4e22ada3854d195d4a18/src/core.js#L371-L373

Fixes #1191

* Assert that the iterator ends

#1197 (comment)

.eslintrc.json

@@ -0,0 +1,31 @@
+{
+  "env": {
+    "node": true
+  },
+  "plugins": ["jsdoc"],
+  "extends": ["eslint:recommended", "prettier"],
+  "globals": {},
+  "rules": {
+    "indent": [
+      2,
+      2,
+      {
+        "SwitchCase": 1,
+        "VariableDeclarator": 2
+      }
+    ],
+    "no-eq-null": 0,
+    "no-proto": 2,
+
+    "jsdoc/check-param-names": 2,
+    "jsdoc/check-tag-names": 2,
+    "jsdoc/check-types": 2,
+    "jsdoc/newline-after-description": 2,
+    "jsdoc/require-description-complete-sentence": 2,
+    "jsdoc/require-hyphen-before-param-description": 2,
+    "jsdoc/require-param": 2,
+    "jsdoc/require-param-description": 2,
+    "jsdoc/require-param-name": 2,
+    "jsdoc/require-param-type": 2
+  }
+}

.gitignore

@@ -7,3 +7,4 @@ lib-cov
 cover_html
 .c9revisions
 coverage
+/docs/

.travis.yml

@@ -1,15 +1,11 @@
 language: node_js
 node_js:
   - "stable"
-  - "unstable"
+  - "8"
   - "6"
-  - "4"
-  - "0.12"
 script: make travis-test
 matrix:
   fast_finish: true
-  allow_failures:
-    - node_js: unstable
   include:
     - env: BENCHMARK=true
       script: "node benchmark/benchmark.js --regex '^(?!.*highmem)'"

CONTRIBUTING.md

@@ -3,16 +3,16 @@
 Thanks for your interest in contributing to the project! Here's a rundown of
 how we'd like to work with you:
 
-1. File an issue on GitHub describing the contribution you'd like to make. This
-   will help us to get you started on the right foot.
-2. Create a single commit that addresses the issue:
-    1. Follow the project's code style (see below)
-    2. Add enough unit tests to "prove" that your patch is correct
-    3. Update the project documentation as needed (see below)
-    4. Describe your approach with as much detail as necessary in the git
-       commit message
-3. Open a pull request, and reference the initial issue in the pull request
-   message.
+1.  File an issue on GitHub describing the contribution you'd like to make. This
+    will help us to get you started on the right foot.
+2.  Create a single commit that addresses the issue:
+    1.  Follow the project's code style (see below)
+    2.  Add enough unit tests to "prove" that your patch is correct
+    3.  Update the project documentation as needed (see below)
+    4.  Describe your approach with as much detail as necessary in the git
+        commit message
+3.  Open a pull request, and reference the initial issue in the pull request
+    message.
 
 # Documentation
 
@@ -22,26 +22,16 @@ care to note aspects that make Cheerio distinct.
 
 # Code Style
 
-This section is by no means complete. For undocumented stylistic choices,
-please try to maintain consistency with the code base.
-
-- Single quotes: `'`
-- Whitespace
-  - Two-space "soft" tabs
-  - Once space following control flow statements (`if (condition) {` rather
-    than `if(condition) {`)
-  - Remove trailing spaces
-  - [End each file with a newline
-    character.](https://github.com/editorconfig/editorconfig/wiki/Newline-at-End-of-File-Support)
-- Terminate every statement with a semicolon
-- Private functionality (for re-using functionality that isn't part of the
-  jQuery API)
-  - *Static methods*: If the functionality does not require a reference to a
-    Cheerio instance, simply define a named function within the module it is
-    needed.
-  - *Instance methods*: If the functionality requires a reference to a Cheerio
-    instance, informally define the method as "private" using the following
-    conventions:
-    - Define the method as a function on the Cheerio prototype
-    - Prefix the method name with an underscore (`_`) character
-    - Include `@api private` in the code comment the documents the method
+Please make sure commit hooks are run, which will enforce the code style.
+
+When implementing private functionality that isn't part of the jQuery API, please opt for:
+
+* _Static methods_: If the functionality does not require a reference to a
+  Cheerio instance, simply define a named function within the module it is
+  needed.
+* _Instance methods_: If the functionality requires a reference to a Cheerio
+  instance, informally define the method as "private" using the following
+  conventions:
+  * Define the method as a function on the Cheerio prototype
+  * Prefix the method name with an underscore (`_`) character
+  * Include `@api private` in the code comment the documents the method

History.md

@@ -1,3 +1,98 @@
+1.0.0-rc.2 / 2017-07-02
+==================
+
+This release changes Cheerio's default parser to [the Parse5 HTML
+parser](https://github.com/inikulin/parse5). Parse5 is an excellent project
+that rigorously conforms to the HTML standard. It does not support XML, so
+Cheerio continues to use [`htmlparser2`](https://github.com/fb55/htmlparser2/)
+when working with XML documents.
+
+This switch addresses many long-standing bugs in Cheerio, but some users may
+experience slower behavior in performance-critical applications. In addition,
+`htmlparser2` is more forgiving of invalid markup which can be useful when
+input sourced from a third party and cannot be corrected. For these reasons,
+the `load` method also accepts a DOM structure as produced by the `htmlparser2`
+library. See the project's "readme" file for more details on this usage
+pattern.
+
+### Migrating from version 0.x
+
+`cheerio.load( html[, options ] )` This method continues to act as a "factory"
+function. It produces functions that define an API that is similar to the
+global `jQuery` function provided by the jQuery library. The generated function
+operates on a DOM structure based on the provided HTML.
+
+In releases prior to version 1.0, the provided HTML was interpreted as a
+document fragment. Following version 1.0, strings provided to the `load` method
+are interpreted as documents. The same example will produce a `$` function that
+operates on a full HTML document, including an `<html>` document element with
+nested `<head>` and `<body>` tags. This mimics web browser behavior much more
+closely, but may require alterations to existing code.
+
+For example, the following code will produce different results between 0.x and
+1.0 releases:
+
+    var $ = cheerio.load('<p>Hello, <b>world</b>!</p>');
+
+    $.root().html();
+
+    //=> In version 0.x: '<p>Hello, <b>world</b>!</p>'
+    //=> In version 1.0: '<html><head></head><body><p>Hello, <b>world</b>!</p></body></html>'
+
+Users wishing to parse, manipulate, and render full documents should not need
+to modify their code. Likewise, code that does not interact with the "root"
+element should not be effected by this change. (In the above example, the
+expression `$('p')` returns the same result across Cheerio versions--a Cheerio
+collection whose only member is a paragraph element.)
+
+However, users wishing to render document fragments should now explicitly
+create a "wrapper" element to contain their input.
+
+    // First, create a Cheerio function "bound" to an empty document (this is
+    // similar to loading an empty page in a web browser)
+    var $ = cheerio.load('');
+    // Next, create a "wrapper" element for the input fragment:
+    var $wrapper = $('<div/>');
+    // Finally, supply the input markup as the content for the wrapper:
+    $wrapper.append('<p>Hello, <b>world</b>!</p>');
+
+    $wrapper.html();
+    //=> '<p>Hello, <b>world</b>!</p>'
+
+---
+
+Change log:
+
+ * Update History.md (and include migration guide) (Mike Pennisi)
+ * Rename `useHtmlParser2` option (Mike Pennisi)
+ * Remove documentation for `xmlMode` option (Mike Pennisi)
+ * Document advanced usage with htmlparser2 (Mike Pennisi)
+ * Correct errors in Readme.md (Mike Pennisi)
+ * Improve release process (Mike Pennisi)
+ * 1.0.0-rc.1 (Mike Pennisi)
+ * Update unit test (Mike Pennisi)
+ * Normalize code style (Mike Pennisi)
+ * Added support for nested wrapping. (Diane Looney)
+ * Add nested wrapping test (Toni Helenius)
+ * Added $.merge following the specification at https://api.jquery.com/jquery.merge/ Added test cases for $.merge (Diane Looney)
+ * Clarify project scope in README file (Mike Pennisi)
+ * .text() ignores script and style tags (#1018) (Haleem Assal)
+ * Test suite housekeeping (#1016) (DianeLooney)
+ * experiment with a job board (Matthew)
+ * Change options format (inikulin)
+ * Add test for #997 (inikulin)
+ * Update .filter function docs. (Konstantin)
+ * Standardise readme on ES6 variable declarations (Dekatron)
+ * Use documents via $.load (inikulin)
+ * Use parse5 as a default parser (closes #863) (inikulin)
+ * Fix small typo in Readme (Darren Scerri)
+ * Report test failures in CI (Mike Pennisi)
+ * serializeArray should not ignore input elements without value attributes (Ricardo Gladwell)
+ * Disallow variable shadowing (Mike Pennisi)
+ * Update hasClass method (sufisaid)
+ * Added MIT License fixes #902 (Prasanth Vaaheeswaran)
+ * chore(package): update dependencies (greenkeeper[bot])
+ * Use modular lodash package (#913) (Billy Janitsch)
 
 0.22.0 / 2016-08-23
 ==================

Makefile

@@ -1,8 +1,9 @@
 REPORTER = dot
 XYZ = node_modules/.bin/xyz --message 'Release X.Y.Z' --tag X.Y.Z --repo git@github.com:cheeriojs/cheerio.git --script scripts/prepublish
+UPSTREAM = git@github.com:cheeriojs/cheerio.git
 
 lint:
-	@./node_modules/.bin/jshint lib/ test/
+	@./node_modules/.bin/eslint --ignore-path .gitignore .
 
 test: lint
 	@./node_modules/.bin/mocha --recursive --reporter $(REPORTER)
@@ -36,4 +37,16 @@ release-patch: LEVEL = patch
 release-major release-minor release-patch:
 	@$(XYZ) --increment $(LEVEL)
 
-.PHONY: test build setup subl
+docs:
+	@./node_modules/.bin/jsdoc --configure jsdoc-config.json
+
+publish-docs: docs
+	@cd docs; \
+		rm -rf .git && \
+		git init && \
+		git add --all . && \
+		git commit -m 'Generate documentation' && \
+		git remote add upstream $(UPSTREAM) && \
+		git push --force upstream master:gh-pages
+
+.PHONY: test build setup subl docs publish-docs