Scrub Banter copyright notices

CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# How to Contribute
+
+I'm happy to take contributions, but there are a few things you need to know.
+
+## Code reviews
+
+I will review all submissions, but reserve the right to decline a particular
+pull request. If you want to do more than fix a bug or correct a typo, please
+[open an issue](https://github.com/jpmedley/MDNBanter/issues) describing your
+idea.
+
+## Community Guidelines
+
+This project uses the [Contributor Covenant Code of Conduct](Contributor Covenant Code of Conduct), version 2.1 ([contributor-covenant.org](https://www.contributor-covenant.org/)).

LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -198,4 +199,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

NOTES.md

@@ -0,0 +1,37 @@
+# Development notes
+
+NOT FOR RELEASE VERSION
+
+## Feature: Memory
+
+When doing multiple methods or properties, some questions have the same answer between members. Why not use the last-provided answer as the default for the current one, provided there is not a default in the questions file.
+
+## Features for later versions
+
+* Build should process partials and callbacks.
+* Interface should handle callbacks. (Currently a dummy value must be entered for -n because a single un-interfaced function cannot be entered.)
+* Build should validate Kuma macros and API identifiers. For kuma macros that generate cross-references, it should ping the url. If 404 comes back, it should search for the IDL and ask appropriate questions.
+* Build should fill in questions that can be answered from the IDL such as whether there's a constructor or whether something is read-only.
+* Make template processing recursive and based on common sections. For example `reference.html` > `_frag_properties.html` > `_frag_property.html`.
+* Output BCD boilerplate for entry and remaining build commands.
+* The prompt for `APIRef()` should display possible values from `GroupData.json`.
+* The prompt for the `APIRef()` macro should invoke a check that it exists in `GroupData.json`.
+* The prompt for `SpecName()` should behave the same as for `APIRef()'
+* The `find` and `build` commands should be able to search on interface members.
+
+## Misc
+
+Here's [an approach to meta-configuration](https://www.keithcirkel.co.uk/metaprogramming-in-es6-symbols/) such as logging and test mode. (Approach is about 1/3 down the page.)
+
+## To Do
+
+* Change `shared:formalAPIName` to `shared:apiName` throughout. Anywhere that it should be suffixed with 'API' add it to the template. Give this a follow-up task that ensures it's not present twice.
+
+* Deal more completely with inheritance.
+
+## Useful Chromium Files
+
+JavaScript built-ins:
+  https://cs.chromium.org/codesearch/f/chromium/src/v8/src/builtins/builtins-definitions.h?cl=HEAD
+
+

README.md

@@ -1,2 +1,151 @@
-# MDNBanter
-Generates templates for MDN reference pages
+# mdn-helper
+Removes repetitive work of creating MDN markup and text. Much of the work of creating a new MDN reference page is in creating boilerplate such as headings, specification tables, and standardized intro text. Once this is created API specific content must be added to the boilerplate. A significant portion of that content is duplicated between one or more pages of the API.
+
+The current version only handles JavaScript APIs.
+
+## Installation
+
+1. Install [node.js](https://nodejs.org), version 12 or later.
+
+1. Clone this repository.
+
+   `git clone https://github.com/jpmedley/mdn-helper.git`
+
+1. Change to the `mdn-helper` directory and run `npm install`.
+
+1. Enter `npm run update-data` to download data files needed for the `build`, `find`, and `report` commands. This script will run automatically on first use if it has been more than twenty-four hours since its last run.
+
+## Usage
+
+From within the mdn-helper direcory:
+
+  `npm run <command> [<arguments>] -- [<flags>]`
+
+## Commands
+
+### build
+
+Searches for APIs with filenames matching the provided string, prompts you to select a specific interface, builds a JSON file for the [Browser compatibility Database](https://github.com/mdn/browser-compat-data), and boilerplate pages formatted for publishing on MDN. 
+
+**Syntax:** `build idl _searchString_ -- [(-i | --interactive)] [(-b | --bcdOnly)]`
+
+For detailed instructions, see [Building MDN Pages](/help/BUILDING-PAGES.md).
+
+### report
+
+Builds several types of reports. This has several syntaxes.
+
+**Syntax:** `report chrome -- [(-f | --flags)] [(-i | --interfaces-only)] [(-o | --origin-trials)] [(-r | --reportinglist) _reportingList_] [(-a | --all)]`
+
+Generates a csv file listing Chrome APIs that are lacking an MDN page. Use `-f` or `--flags` to include APIs behind a flag. Use `-i` or `--interfaces-only` run a report containing only interfaces. Use `-o` or `--origin-trials` to include APIs currently in a Chrome origin trial. Use `-w` or `--reportinglist` report on a specific list of interfaces. Use `-a` or `--all` to run a report that lists all IDL members whether documented or not.
+
+**Syntax:** `report urls -- [(-c | --category) _category_]`
+
+Generates a csv listing BCD entries that are lacking a corresponding MDN page. `_category_` must be one of 'api', 'css', 'html', 'javascript', or 'svg'. If you don't enter one of these values, you will be prompted for one of them.
+
+**Syntax:** `report bcd -- [(-c | --category) _category_] [(-b | --browsers) _browsers_]`
+
+Generates a csv listing BCD entries where the browser value is either null or missing.
+
+* `_category_` must be one of 'api', 'css', 'html', 'javascript', or 'svg'. If you don't enter one of these values, you will be prompted for one of them.
+* `_browsers_` must be a comma-separated list of browsers. If you don't enter any browsers or one of the provided browser names is not valid, you will be prompted to select browsers from a list.
+
+### clean
+
+Deletes selected folders from the `*path/to*/mdn-helper/out/` directory.
+
+**Syntax:** `clean`
+
+### find
+
+Searches for interfaces matching the provided string, prompts you to select a specific file, then displays the Chrome IDL file for that interface. (For an explanation of why it uses Chrome, see [Data Sources](#data-sources), below.)
+
+**Syntax:** `find idl _searchString_ -- [(-p | --ping)]`
+
+**Flag:**
+
+`-p` or `--ping`: (Optional) Pings the MDN pages for the interface members and
+display whether they exist.
+
+### header
+
+Creates pages for the provided HTTP header and directive names names. The results are written to the `*path/to*/mdn-helper/out/` directory. To build directive plages only, exclude the -H or --header flag.
+
+**Syntax:** <code>header -- -n _headerName_ [(-H | --header)] [(-d | --directive) _directiveName_]</code>
+
+**Flags:**
+
+`-n`: The name of the header being documented. This flag provides the header\'s name for use in directive pages. It does not create an interface page.
+
+At least one of the following:
+* `-H` or `--header`: (Optional) Indicates that a header page *should be created*. If this flag is absent only directive pages will be created.
+* `-d` or `--directive`: (Optional) The name of a directive being documented. This flag may be repeated as needed.
+
+### interface
+
+Creates one or more individual boilerplates for JavaScript platform APIs. The results are written to the `*path/to*/mdn-helper/out/` directory. The syntax description makes this look more complicated than it is. This can be summarized as `interface -n _interfaceName_` followed by commands for one or more individual pages. For example, the following would create a boilerplate for a property:
+
+`npm run interface -n CSSTransformValue -p length`
+
+Note that this command cannot create multiple pages of the same time in a single command. For example, to create boilerplates for two properties, you would need to run the command twice.
+
+**Syntax:** <code>interface -n _interfaceName_ [-l] [-r] [-c] [(-e | --event) _eventName_] [(-h | --handler) _handlerName_] [(-m | --method) _methodName_] [(-p | --property) _propertyName_] [(-w | --writefiles)</code>
+
+**Flags:**
+
+`-n`: The name of the interface being documented. This flag provides the interface\'s name for use in member pages. It does not create an overview, interface, or constructor page.
+
+At least one of the following:
+* `-l` or `--landing`: (Optional) Indicates that a [landing page](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Page_types/API_landing_page_template) should be created.
+* `-r` or `--reference`: (Optional) Indicates that an [interface reference page](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Page_types/API_reference_page_template) should be created.
+* `-c`: (Optional) Indicates that a [constructor page](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Page_types/API_constructor_subpage_template) should be created.
+* `-it`: (Optional) Indicates that pages for the functions of the *iterable* IDL type will be created, specifically entries(), forEach(), keys(), and values().
+* `-mp`: (Optional) Indicates that pages for the functions of the *maplike* IDL type will be created.
+* `-mr`: (Optional) Indicates that pages for the functions of the *readonly maplike* IDL type will be created.
+* `-e` or `--event`: (Optional) Indicates that an *event* page should be created with the specified name. This flag may be repeated as needed.
+* `-h` or `--handler`: (Optional) Indicates that an [event handler page](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Page_types/API_event_handler_subpage_template) should be created with the specified name. This flag may be repeated as needed.
+* `-m` or `--method`: (Optional) Indicates that a [method page](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Page_types/API_method_subpage_template) should be created with the specified name. This flag may be repeated as needed.
+* `-p` or `--property`: (Optional) Indicates that a [property page](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Page_types/API_property_subpage_template) should be created with the specified name. This flag may be repeated as needed.
+* `-` or `--writefiles`: (Optional) The pages will not be created interactively, but will be written directly to the output directory.
+
+## update-data
+
+Downloads a new set of IDL files for use by the `build`, `find`, and `report` commands. This command will run automatically either daily or weekly depending on the value set in your config file. Use `-s` or `--sooner` to update data sooner.
+
+### help
+
+Prints help text to the console.
+
+## Examples
+
+**Create an interface page only**
+
+`node index.js interface -n Widget -i`
+
+**Create an interface page and a constructor page**
+
+`node index.js interface -n Widget -i -c`
+
+**Create a method page without its interface**
+
+`node index.js interface -n Widget -m "doStuff()"`
+
+**Create an interface page and two members**
+
+`node index.js interface -n Widget -m "doStuff()" -p isReady`
+
+## configuration
+
+When installed, no configuration is needed. [Instructions are provided](help/CONFIGURING.md) for a few options that you may want to change.
+
+## Data Sources
+
+MDN Helper uses Chrome as its starting point because of the ease of reading API surfaces from its source code as compared to other browsers and because Chrome is often the first browser to implement new web platform features. (If you know of an easily downloaded data set that is a reliable proxy for the features of another browser, please contact me at the email address in my GitHub profile.)
+
+MDN Helper does not use data in web platform specs because working out which version of a spec to use as a starting point is not something that can be done algorithmically. Also, this tool was created to assist with new web platform features. For such featues, the first implementation may not include every feature described in a spec. Those unimplemented features can and do go through design changes before implementation.
+
+If you need to document a new feature that was implemented by a browser other than Chrome, see [Documenting New Features](help/BUILDING-PAGES.md#documenting-new-features).
+
+## Contributing
+
+We'd love to accept your patches and contributions. See our [contributing page](CONTRIBUTING.md) for instructions on how.

actions/add_block.js

@@ -0,0 +1,27 @@
+// Copyright 2024 Joseph P Medley
+
+'use strict';
+
+const page = require('../page.js');
+
+async function _run(currentPage, question) {
+  // const answer = question.answer.toLowerCase();
+  // if (answer.startsWith('n')) {
+  //   question.answer = '';
+  //   return;
+  // }
+  if (!question.answer) { return; }
+  const tempPage = new page.Page('temporary', question.action.args[0], currentPage.sharedQuestions);
+  let msg;
+  if (currentPage.sharedQuestions.needsAnswers()) {
+    msg = "More shared shared questions found."
+    await currentPage.sharedQuestions.askQuestions(msg);
+  }
+  if (tempPage.questions.needsAnswers()) {
+    msg = `\tYou will now be asked to provide answers for ${question.name}.`;
+    await tempPage.askQuestions(msg);
+  }
+  question.answer = tempPage.contents;
+}
+
+module.exports.run = _run;