New dependency parser and introduce # delimiter

CHANGELOG.md

@@ -6,7 +6,36 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic
 Versioning](https://semver.org/spec/v2.0.0.html).
 
-<!-- ## Unreleased -->
+## Unreleased
+
+### Changed
+
+- It is now supported _and preferred_ to use `#` as the delimiter between
+  packages and scripts in dependency specifiers, instead of `:`. For example,
+  instead of `"../other:build"`, it is now preferred to write
+  `"../other#build"`.
+
+  The `:` character will continue to work the same indefinitely, but the Wireit
+  documentation will exclusively show `#`, and upcoming new features for
+  dependency specifiers will only work with the newer `#` form.
+
+- **[BREAKING]** Certain special characters must now be escaped with a `\`
+  (which in JSON is written as `\\`) if they are to be intepreted literally in a
+  package specifier:
+
+  - `#`
+  - `\`
+  - `<`
+  - `>`
+  - `.` (only required at the start of the specifier)
+  - `!` (only required at the start of the specifier)
+  - `:` (only required when using the legacy delimiter, meaning a `#` does not
+    appear later in the specifier)
+
+  For example, in the (highly unusual) situation that you depend on a script
+  like `"../ha#shy:sl\\ashy"`, you should now write `"../ha\\#shy#sl\\\\ashy"`
+  (note that `\` escapes are _also_ required for JSON, hence the double
+  escapes).
 
 ## [0.14.11] - 2025-02-07
 

README.md

@@ -171,10 +171,15 @@ other wireit scripts, and can never be run directly.
 ### Cross-package dependencies
 
 Dependencies can refer to scripts in other npm packages by using a relative path
-with the syntax `<relative-path>:<script-name>`. All cross-package dependencies
+with the syntax `<relative-path>#<script-name>`. All cross-package dependencies
 should start with a `"."`. Cross-package dependencies work well for npm
 workspaces, as well as in other kinds of monorepos.
 
+> [!NOTE]
+> The `:` character can also be used as a delimiter instead of `#` (e.g.
+> `"../other-package:build`), but `#` is preferred since February 2025 because
+> it is less ambiguous given the prevalence of `:` in npm script names.
+
 ```json
 {
   "scripts": {
@@ -183,7 +188,7 @@ workspaces, as well as in other kinds of monorepos.
   "wireit": {
     "build": {
       "command": "tsc",
-      "dependencies": ["../other-package:build"]
+      "dependencies": ["../other-package#build"]
     }
   }
 }
@@ -534,7 +539,7 @@ expected to exit by itself, set `"service": true`.
       "dependencies": [
         "build:server",
         {
-          "script": "../assets:build",
+          "script": "../assets#build",
           "cascade": false
         }
       ]
@@ -691,7 +696,7 @@ There are two main reasons you might want to set `cascade` to `false`:
          "dependencies": [
            "build:server",
            {
-             "script": "../assets:build",
+             "script": "../assets#build",
              "cascade": false
            }
          ],
@@ -853,7 +858,7 @@ The following properties can be set inside `wireit.<script>` objects in
 | ------------------------- | ---------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
 | `command`                 | `string`                           | `undefined`             | The shell command to run.                                                                                                       |
 | `dependencies`            | `string[] \| object[]`             | `[]`                    | [Scripts that must run before this one](#dependencies).                                                                         |
-| `dependencies[i].script`  | `string`                           | `undefined`             | [The name of the script, when the dependency is an object.](#dependencies).                                                     |
+| `dependencies[i].script`  | `string`                           | `undefined`             | [The name of the script, when the dependency is an object](#dependencies).                                                      |
 | `dependencies[i].cascade` | `boolean`                          | `true`                  | [Whether this dependency always causes this script to re-execute](#execution-cascade).                                          |
 | `files`                   | `string[]`                         | `undefined`             | Input file [glob patterns](#glob-patterns), used to determine the [fingerprint](#fingerprint).                                  |
 | `output`                  | `string[]`                         | `undefined`             | Output file [glob patterns](#glob-patterns), used for [caching](#caching) and [cleaning](#cleaning-output).                     |

package.json

@@ -40,6 +40,7 @@
     "test:codeactions": "wireit",
     "test:copy": "wireit",
     "test:delete": "wireit",
+    "test:dependency-parser": "wireit",
     "test:diagnostic": "wireit",
     "test:errors-analysis": "wireit",
     "test:errors-usage": "wireit",
@@ -93,6 +94,7 @@
         "test:codeactions",
         "test:copy",
         "test:delete",
+        "test:dependency-parser",
         "test:diagnostic",
         "test:errors-analysis",
         "test:errors-usage",
@@ -223,6 +225,17 @@
       "files": [],
       "output": []
     },
+    "test:dependency-parser": {
+      "command": "uvu lib/test \"^dependency-parser\\.test\\.js$\"",
+      "env": {
+        "NODE_OPTIONS": "--enable-source-maps"
+      },
+      "dependencies": [
+        "build"
+      ],
+      "files": [],
+      "output": []
+    },
     "test:diagnostic": {
       "command": "uvu lib/test \"^diagnostic\\.test\\.js$\"",
       "env": {