Rename "commands" to "tags" (#84)

* Rename "commands" to "tags"

Motivation:
- we already have CLI "commands"
- "tags" more closely maps to how you use them

* Rename CONSTANTS

* Fix up documentation

CONTRIBUTING.md

@@ -55,34 +55,34 @@ You can also run tests with breakpoints in VS Code with F5. See .vscode/launch.j
 Bluehawk has three major components:
 
 - **Client:** loads files to be parsed and processed. Implements listeners that
-  decide what to do with results (e.g. save to file). Can add custom commands
+  decide what to do with results (e.g. save to file). Can add custom tags
   and language specifications (i.e. comment syntax). The main client is the CLI,
   but you can use Bluehawk as a library and implement your own clients.
-- **Parser:** finds commands in a source file and diagnoses markup errors.
-- **Processor:** executes commands on a source file to produce transformed documents.
+- **Parser:** finds tags in a source file and diagnoses markup errors.
+- **Processor:** executes tags on a source file to produce transformed documents.
 
 ## File Language-Specific Tokens
 
 The lexer can receive custom tokens for a given language to define comment
 syntax. For example, plaintext has no comments, bash only has line comments
 (#)[†](https://stackoverflow.com/questions/32126653/how-does-end-work-in-bash-to-create-a-multi-line-comment-block),
 and C++ has line (//) and block (`/*`, `*/`) comments. Bluehawk is comment aware so
-that it can correctly strip comments (when needed) and diagnose when commands
+that it can correctly strip comments (when needed) and diagnose when tags
 are halfway in a block comment.
 
-## Command Tokens
+## Tag Tokens
 
 ":snippet-start:", ":remove-start:", etc. are not keywords. Instead, the
-lexer and parser detect [command], [command]-start, and [command]-end. It is up
-to the visitor to determine whether the -start and -end command names match and
-if the command name is understood by Bluehawk. This keeps the lexer and parser
+lexer and parser detect [tag], [tag]-start, and [tag]-end. It is up
+to the visitor to determine whether the -start and -end tag names match and
+if the tag name is understood by Bluehawk. This keeps the lexer and parser
 simpler and allows for extensibility of Bluehawk as users could eventually
-provide their own commands.
+provide their own tags.
 
 ## Attribute Lists
 
 The original Bluehawk spec document included the ability to provide a JSON
-object after a block command to configure the block command's attributes. The
-lexer has "modes" so after it encounters a block command, it goes into an
-attribute mode, which will either accept the command identifier (i.e.
-:some-command-start: this-is-the-identifier) or the attribute list JSON.
+object after a block tag to configure the block tag's attributes. The
+lexer has "modes" so after it encounters a block tag, it goes into an
+attribute mode, which will either accept the tag identifier (i.e.
+:some-tag-start: this-is-the-identifier) or the attribute list JSON.

docs/README.md

@@ -23,7 +23,7 @@ From the `/docs` folder:
 npm start
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+This tag starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
 ## Build
 
@@ -33,11 +33,11 @@ From the `/docs` folder:
 npm run build
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+This tag generates static content into the `build` directory and can be served using any static contents hosting service.
 
 ## Deployment
 
-The docs autodeploy with a Github action. If you need to manually deploy the docs, run this command from the `/docs` folder:
+The docs autodeploy with a Github action. If you need to manually deploy the docs, run this tag from the `/docs` folder:
 
 ```shell
 GIT_USER=<Your GitHub username> USE_SSH=true npm run deploy

docs/docs/cli.md

@@ -11,21 +11,17 @@ custom_edit_url: null
 Use commands to generate different kinds of output with Bluehawk, including
 code blocks, full files of code, and even error checks.
 
-> 💡 Commands for the Bluehawk CLI are not the same as
-> [Bluehawk Commands](./commands), the syntax
-> interpreted by Bluehawk to process input files.
-
 ### Snip
 
 ```
 bluehawk snip --destination <output-directory> <input-directory-or-file>
 ```
 
 Output "snippet files" that contain only the content of `code-block` or
-`snippet` Bluehawk commands, named in the format
+`snippet` Bluehawk tags, named in the format
 `<source-file-name>.codeblock.<codeblock-name>.<source-file-extension>`.
 By default, this command generates snippets
-that omit all `state` command contents. However,
+that omit all `state` tag contents. However,
 you can use the `--state` flag to generate snippet files that include
 content from a single state that you specify.
 
@@ -51,7 +47,7 @@ bluehawk check <input-directory-or-file>
 
 Generates non-zero output if processing any input files generates a Bluehawk
 error, zero output otherwise. Does not generate any files: instead, `check`
-outputs directly to command line.
+outputs directly to the command line.
 
 ## Flags
 

docs/docs/plugins.md

@@ -6,17 +6,17 @@ sidebar_position: 4
 custom_edit_url: null
 ---
 
-You can add commands and listeners by creating a JS file or node project that
-implements the register() function:
+You can add tags, CLI commands, and listeners by creating a JS file or node
+project that implements the register() function:
 
 ```js
 // myPlugin.js
 exports.register = (bluehawk) => {
-  // Register a new command, :my-command:
-  bluehawk.registerCommand("my-command", {
+  // Register a new tag, :my-tag:
+  bluehawk.registerTag("my-tag", {
     rules: [],
     process: (request) => {
-      // Execute command
+      // Execute tag
     },
   });
 

docs/docs/commands.md → docs/docs/tags.md

@@ -1,22 +1,22 @@
 ---
-id: "commands"
-title: "Commands"
-sidebar_label: "Commands"
+id: "tags"
+title: "Tags"
+sidebar_label: "Tags"
 sidebar_position: 1
 custom_edit_url: null
 ---
 
-Bluehawk **commands** come in two forms: _single-line_ and _block_. Single-line commands
-operate upon the current line, while block commands operate upon the span of lines between
-the start of the command and the end of the command. Since commands aren't valid syntax in
+Bluehawk **tags** come in two forms: _single-line_ and _block_. Single-line tags
+operate upon the current line, while block tags operate upon the span of lines between
+the start of the tag and the end of the tag. Since tags aren't valid syntax in
 most languages, you should place them in comments -- Bluehawk will still process them.
-To avoid name clashes with various languages and markup frameworks, all Bluehawk commands
+To avoid name clashes with various languages and markup frameworks, all Bluehawk tags
 begin and end with colons (`:`).
 
 The following examples demonstrate the [remove](#remove)
-command in single-line and block forms:
+tag in single-line and block forms:
 
-Single-line commands use `:<command>:` to markup a single line:
+Single-line tags use `:<tag>:` to mark up a single line:
 
 ```java
 public class Main {
@@ -30,7 +30,7 @@ public class Main {
 }
 ```
 
-Block commands use `:<command>-start:` and `:<command>-end:` to mark the beginning and end
+Block tags use `:<tag>-start:` and `:<tag>-end:` to mark the beginning and end
 of a spanned range of lines:
 
 ```java
@@ -47,10 +47,10 @@ public class Main {
 }
 ```
 
-Some commands, like `remove` in the examples above, don't require any arguments at all.
-Other commands, such as `snippet`, require a unique (to that file) identifier. Yet other
-commands, such as `replace`, require an [attribute list](#attribute-lists) of JSON objects. Pass arguments to
-commands by listing them after the command itself:
+Some tags, like `remove` in the examples above, don't require any arguments at all.
+Other tags, such as `snippet`, require a unique (to that file) identifier. Yet other
+tags, such as `replace`, require an [attribute list](#attribute-lists) of JSON objects. Pass arguments to
+tags by listing them after the tag itself:
 
 ```java
 public class Main {
@@ -68,30 +68,30 @@ public class Main {
 }
 ```
 
-> 💡 For a summary of all of the commands available in your local installation
-> of Bluehawk, run `bluehawk list commands`.
+> 💡 For a summary of all of the tags available in your local installation
+> of Bluehawk, run `bluehawk list tags`.
 
 ## Attribute Lists
 
-Attribute lists are JSON objects that contain additional information about a command.
+Attribute lists are JSON objects that contain additional information about a tag.
 They must use double quotes for fields, and the opening line of an attribute list
-must appear on the same line as the command itself.
+must appear on the same line as the tag itself.
 
 ```java
-// :command: {
+// :some-tag-start: {
 //    "field": "value"
 // }
-// :replace-end:
+// :some-tag-end:
 ```
 
 ## Snippet
 
-The `snippet` command, also aliased as `code-block`, marks a range of content in a file
+The `snippet` tag, also aliased as `code-block`, marks a range of content in a file
 as a snippet. You can use the [snip](#snip) CLI command to generate snippet files from
 these snippets.
 
 Because `snippet` operates on ranges of content, it is only available as
-a block command. You must pass `snippet` an identifier.
+a block tag. You must pass `snippet` an identifier.
 
 Consider the following file:
 
@@ -123,7 +123,7 @@ System.out.println("Hello world!");
 
 ## State
 
-The `state` command marks a range of content in a file as part of a particular state.
+The `state` tag marks a range of content in a file as part of a particular state.
 You can use the [snip](#snip) or [copy](#copy) CLI commands with the [state](#state)
 flag to generate output files that contain only content from a specific named state.
 When you use the `--state` flag to specify a state, all state blocks other than the
@@ -135,10 +135,10 @@ with multiple steps, such as a "start" state that only contains `// TODO` and a
 "final" state that contains completed implementation code.
 
 Because `state` operates on ranges of content, it is only available as
-a block command. You must pass `state` at _least one_ identifier, which determines
+a block tag. You must pass `state` at _least one_ identifier, which determines
 the name of the state or states that the block belongs to. You can pass
 in a list of identifiers either through a space-separated list directly after
-the command itself, or through the `id` field of an [attribute list](#attribute-lists).
+the tag itself, or through the `id` field of an [attribute list](#attribute-lists).
 
 Consider the following file:
 
@@ -195,14 +195,14 @@ example++;
 
 ## State-Uncomment
 
-The `state-uncomment` command combines the [state](#state) and [uncomment](#uncomment)
-commands. In terms of syntax, `state-uncomment` works exactly the same as `state`,
+The `state-uncomment` tag combines the [state](#state) and [uncomment](#uncomment)
+tags. In terms of syntax, `state-uncomment` works exactly the same as `state`,
 except one layer of commenting is removed from the entire state in produced output.
 Use `state-uncomment` to prevent executable code in a state from actually executing
 in the source code you use to produce output.
 
 Because `state-uncomment` operates on ranges of content, it is only available as
-a block command.
+a block tag.
 
 Consider the following file:
 
@@ -249,14 +249,14 @@ one of those states when executing your source code.
 
 ## Uncomment
 
-The `uncomment` command removes a single comment from the beginning of
+The `uncomment` tag removes a single comment from the beginning of
 each line of the spanned range in all output.
 
 Because `uncomment` operates on ranges of content, it is only available as
-a block command.
+a block tag.
 
 > 💡 Comments are only specified in certain language types. For example, plaintext
-> does not have a comment syntax, so this command does nothing in plaintext.
+> does not have a comment syntax, so this tag does nothing in plaintext.
 
 Consider the following file:
 
@@ -298,14 +298,14 @@ public class Main {
 
 ## Replace
 
-The `replace` command accepts a JSON dictionary called "terms" as input
+The `replace` tag accepts a JSON dictionary called "terms" as input
 via an attribute list, and replaces occurrences string keys in the map within
 the spanned range with their map values in all output. You can use
 `replace` to hide implementation details like complicated class names
 or API endpoint URLs in generated output.
 
 Because `replace` operates on ranges of content, it is only available
-as a block command. You must pass an attribute list containing "terms",
+as a block tag. You must pass an attribute list containing "terms",
 a dictionary of strings to strings.
 
 Consider the following file:
@@ -362,14 +362,14 @@ public class Main {
 
 ## Emphasize
 
-The `emphasize` command highlights marked lines in formatted output.
+The `emphasize` tag highlights marked lines in formatted output.
 `emphasize` makes it easier to keep the correct lines highlighted
 when you update code samples, because it calculates the highlighted
 line numbers for you.
 
-You can use `emphasize` as either a block command or a line command.
+You can use `emphasize` as either a block tag or a line tag.
 
-> 💡 The emphasize command only applies to [formatted output](./cli#format).
+> 💡 The emphasize tag only applies to [formatted output](./cli#format).
 > Use the `--format` flag with Bluehawk CLI to get formatted output.
 
 Consider the following file:
@@ -411,12 +411,12 @@ Produces the following output:
 
 ## Remove
 
-The `remove` command, also aliased as `hide`, removes the spanned
+The `remove` tag, also aliased as `hide`, removes the spanned
 range from Bluehawk output. `remove` can be helpful for hiding
 assertions and state setup from user-facing code samples.
 
-You can use `remove` as either a block command or a
-line command.
+You can use `remove` as either a block tag or a
+line tag.
 
 Consider the following file:
 

docs/docs/use-cases.md

@@ -9,7 +9,7 @@ custom_edit_url: null
 ### Tested Code Examples
 
 Imagine you want to paste some code from a unit test into your docs. You can
-mark up the unit test source file like this with Bluehawk commands like
+mark up the unit test source file like this with Bluehawk tags like
 `:snippet-start:`, `:snippet-end:`, `:remove-start:`, and `:remove-end:`:
 
 ```swift
@@ -59,7 +59,7 @@ branches, which can be tedious and error prone.
 
 To manage this process, you can use Bluehawk to mark up your tutorial source and
 indicate different states or checkpoints with the `:state-start:` and
-`:state-end:` commands:
+`:state-end:` tags:
 
 ```swift
 // WelcomeViewController.swift

docs/docusaurus.config.js

@@ -68,7 +68,7 @@ const config = {
                 to: "/",
               },
               {
-                label: "Commands",
+                label: "Tags",
                 to: "/commands",
               },
               {

src/bluehawk/Document.ts

@@ -3,7 +3,7 @@ import * as Path from "path";
 import { SourceMapConsumer } from "source-map";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type CommandAttributes = { [forCommandName: string]: any };
+export type TagAttributes = { [forTagName: string]: any };
 
 /**
   Represents a file either before or after processing.
@@ -62,12 +62,12 @@ export class Document {
   readonly modifiers: { [key: string]: string };
 
   /**
-    Attributes that a command can store information in for later processing by
+    Attributes that a tag can store information in for later processing by
     listeners.
 
     These do not affect the identity of the document.
    */
-  attributes: CommandAttributes;
+  attributes: TagAttributes;
 
   /**
     Returns the name of the file minus the file extension.
@@ -106,7 +106,7 @@ export class Document {
     text: string | MagicString;
     path: string;
     modifiers?: { [key: string]: string };
-    attributes?: CommandAttributes;
+    attributes?: TagAttributes;
   }) {
     this.text =
       typeof text === "string" || text instanceof String