doc: rewrites copy on experimental features (which in some cases were…

…n't experimental anymore)

- adds x-dot-webpage to the reporters
- removes 'experimental' notices for features that have been part of dependency-cruiser for ages (and work just fine)
- uses github specific alerts syntax for notes & warnings
- uniformly use the 💡 emoji to prefix usage notes
- renames the (undocumented) 'experimental-scripts' oneShot --init option to 'x-scripts' to remain consistent with e.g. x-dot-webpage

bin/dependency-cruise.mjs

@@ -109,7 +109,7 @@ try {
     .addOption(
       new Option(
         "-d, --max-depth <n>",
-        "You probably want to use --collapse instead of --max-depth. " +
+        "you probably want to use --collapse instead of --max-depth. " +
           "(max-depth would limit the cruise depth; 0 <= n <= 99 (default: 0 - no limit)).",
       ).hideHelp(true),
     )
@@ -125,13 +125,13 @@ try {
     )
     .option(
       "-C, --cache [cache-directory]",
-      "(experimental) use a cache to speed up execution. " +
+      "use a cache to speed up execution. " +
         "The directory defaults to node_modules/.cache/dependency-cruiser",
     )
     .addOption(
       new Option(
         "--cache-strategy <strategy>",
-        "(experimental) strategy to use for detecting changed files in the cache.",
+        "strategy to use for detecting changed files in the cache.",
       ).choices(["metadata", "content"]),
     )
     .addOption(

doc/cli.md

@@ -197,6 +197,23 @@ As a comparison, this is the default dot report for the same folder(s)
 This too is a reporter that shows the modules' instability metrics when they
 have been calculated ([--metrics](#--metrics) command line switch).
 
+#### x-dot-webpage
+
+Reporter that runs the dot reporter and pipes it through the GraphViz `dot`
+command and wraps the result in an html page. It's the same thing as running ...
+
+```sh
+dependency-cruise -T dot src | dot -T svg | depcruise-wrap-stream-in-html > dependencygraph.html
+```
+
+... but less typing & easier to remember.
+
+> [!NOTE]
+> The `x` in front of the name of the reporter means it is experimental and
+> might change or be removed in the future. See the
+> [pull request that introduced the reporter](https://github.com/sverweij/dependency-cruiser/pull/907)
+> for the rationale.
+
 #### mermaid
 
 Generates a graph in mermaid format - which can be convenient as e.g. GitHub and
@@ -301,7 +318,7 @@ results in a PR - potentially along with the mermaid reporter. The markdown
 reporter is fairly configurable - see the [markdown](./options-reference.md#markdown)
 section in the options reference for details.
 
-> [!note]
+> [!NOTE]
 > As compared to the `err-html` reporter this one doesn't emit links or show
 > a complete list of all run validations. If you need that: create a feature
 > request in the dependency-cruiser repo.

doc/rules-reference.md

@@ -278,16 +278,12 @@ a difference:
   depends on `main/utl.js` there is no circular dependency on module level,
   but there _is_ one between the `main` and `utl` folders
 
-> - :warning: the _scope_ attribute is _experimental_. The attribute was introduced
->   to enable folder scope validations. Whether this is the best approach to
->   distinguish folder and module scope validations has to be proven over time.
->   If there's a better way dependency-cruiser will switch over to that without
->   a major version bump.
-> - :warning: at this time only the `moreUnstable`, `circular` and `path`/ `pathNot`
->   attributes (including 'group matching') work, so it is
->   possible to check the "stable dependencies principle" on folder level. Other
->   attributes (including, but not limited to _via_)
->   still have to be implemented (after release 11.7.0)
+> [!NOTE]
+> at this time only the `moreUnstable`, `circular` and `path`/ `pathNot`
+> attributes (including 'group matching') work, so it is
+> possible to check the "stable dependencies principle" on folder level. Other
+> attributes (including, but not limited to _via_)
+> still have to be implemented (after release 11.7.0)
 
 ## Conditions
 
@@ -479,7 +475,7 @@ To detect orphan guys you can add e.g. this snippet to your
 
 #### Usage notes
 
-- dependency-cruiser will typically not find orphans when you give it
+- :bulb: dependency-cruiser will typically not find orphans when you give it
   only one module to start with. Any module it finds, it finds by
   following its dependencies, so each module will have at least one
   dependency incoming or outgoing. Specify one or more folder, several
@@ -493,10 +489,10 @@ To detect orphan guys you can add e.g. this snippet to your
   depcruise -v -- src/index.ts
   ```
   probably won't (unless index.ts is an orphan itself).
-- by definition orphan modules have no dependencies. So when `orphan` is
+- :bulb: by definition orphan modules have no dependencies. So when `orphan` is
   part of a rule, the `to` part won't make sense. This is why
   dependency-cruiser will ignore the `to` part of these rules.
-- For similar reasons `orphan` is not allowed in the `to` part of rules.
+- :bulb: For similar reasons `orphan` is not allowed in the `to` part of rules.
 
 ### `reachable` - detecting dead wood and transient dependencies
 
@@ -590,10 +586,10 @@ happens:
 
 #### Usage notes
 
-- You can set up multiple rules with a `reachable` attribute in the `to` section. If you do so,
+- :bulb: You can set up multiple rules with a `reachable` attribute in the `to` section. If you do so,
   make sure you give a `name` to each rule. It's not only the only way dependency-cruiser can keep
   reachable rules apart - it will be for you as well :-).
-- Different from other rules, rules with a `reachable` attribute can only have
+- :bulb: Different from other rules, rules with a `reachable` attribute can only have
   - `path` and `pathNot` in the `from` part of the rule
   - `path` and `pathNot` alongside the `reachable` in the `to` part of the rule  
     (these limitations might get lifted somewhere in the future)
@@ -623,11 +619,11 @@ E.g. to flag modules in the `shared` folder that are only used from the
 
 #### Usage notes
 
-- Currently rules on dependents only work within the `forbidden` context.
-- In the `from` part `path` and `pathNot` attributes work, but none other.
-- Similarly the `to` part of the rule can (next to the `numberOfDependentsLessThan`
+- :bulb: Currently rules on dependents only work within the `forbidden` context.
+- :bulb: In the `from` part `path` and `pathNot` attributes work, but none other.
+- :bulb: Similarly the `to` part of the rule can (next to the `numberOfDependentsLessThan`
   attribute) also only use `path` and `pathNot`.
-- You can't use group matching with this rule.
+- :bulb: You can't use group matching with this rule.
   <details>
   <summary>why?</summary>
 
@@ -894,9 +890,10 @@ legal department):
 > Just with _path_ and _pathNot_ you can pass an array of regular expressions
 > as well if you think that's more legible.
 
-Note: dependency-cruiser can help out a bit here, but you remain responsible
-for managing your own legal stuff. To re-iterate what is in the
-[LICENSE](../LICENSE) to dependency-cruiser:
+> [!NOTE]
+> dependency-cruiser can help out a bit here, but you remain responsible
+> for managing your own legal stuff. To re-iterate what is in the
+> [LICENSE](../LICENSE) to dependency-cruiser:
 
 > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 > IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
@@ -1161,8 +1158,9 @@ make it beyond the pre-compilation step:
 }
 ```
 
-:warning: This attribute only works for TypeScript sources, and only when
-[`tsPreCompilationDeps`](#tsprecompilationdeps) option is set to `"specify"`.
+> [!NOTE]
+> This attribute only works for TypeScript sources, and only when
+> [`tsPreCompilationDeps`](#tsprecompilationdeps) option is set to `"specify"`.
 
 ### `moreUnstable`
 

src/cli/init-config/index.mjs

@@ -50,7 +50,7 @@ function getOneShotConfig(pOneShotConfigId) {
   const lOneShotConfigs = new Map([
     ["yes", lBaseConfig],
     [
-      "experimental-scripts",
+      "x-scripts",
       {
         updateManifest: fileExists(PACKAGE_MANIFEST),
         ...lBaseConfig,

src/cli/init-config/types.d.ts

@@ -1,4 +1,4 @@
-export type OneShotConfigIDType = "yes" | "experimental-scripts";
+export type OneShotConfigIDType = "yes" | "x-scripts";
 
 export interface IInitConfig {
   /**

test/cli/init-config/index.spec.mjs

@@ -152,7 +152,7 @@ describe("[I] cli/init-config/index", () => {
     }
   });
 
-  it("init experimental-scripts creates a .dependency-cruiser config + updates package.json with scripts", async () => {
+  it("init x-scripts creates a .dependency-cruiser config + updates package.json with scripts", async () => {
     const lOutStream = new WritableTestStream(
       /(Successfully created '.dependency-cruiser.js'|Run scripts added to '[.]\/package.json':)/,
     );
@@ -167,7 +167,7 @@ describe("[I] cli/init-config/index", () => {
     writeFileSync(lManifestFilename, "{}");
 
     try {
-      initConfig("experimental-scripts", null, {
+      initConfig("x-scripts", null, {
         stdout: lOutStream,
         stderr: lErrorStream,
       });
@@ -183,7 +183,7 @@ describe("[I] cli/init-config/index", () => {
     }
   });
 
-  it("init experimental-scripts updates package.json with scripts, and leaves an existing dc config alone", async () => {
+  it("init x-scripts updates package.json with scripts, and leaves an existing dc config alone", async () => {
     const lOutStream = new WritableTestStream(
       /Run scripts added to '[.]\/package.json':/,
     );
@@ -199,7 +199,7 @@ describe("[I] cli/init-config/index", () => {
     writeFileSync(lManifestFilename, "{}");
 
     try {
-      initConfig("experimental-scripts", null, {
+      initConfig("x-scripts", null, {
         stdout: lOutStream,
         stderr: lErrorStream,
       });

tools/schema/options.mjs

@@ -387,12 +387,7 @@ export default {
           type: "object",
           additionalProperties: false,
           description:
-            "When executing dependency-cruiser emits 'start', 'progress' and 'end' events on " +
-            "a bus. You can use these e.g. to show progress in any UI (e.g. the cli) attach " +
-            "loggers etc. We're still figuring out how to do expose this (if at all), so the " +
-            "listener feature is highly experimental and use in any environment outside " +
-            "playgrounds is discouraged. For now it's only possible to use one of the " +
-            "baked-in listeners.",
+            "How dependency-cruiser shows progress. Defaults to 'none'.",
           properties: {
             type: {
               type: "string",

tools/schema/restrictions.mjs

@@ -237,7 +237,6 @@ export default {
             "Matches when the number of times the 'to' module is used falls below (<) " +
             "this number. Caveat: only works in concert with path and pathNot restrictions " +
             "in the from and to parts of the rule; other conditions will be ignored." +
-            "(somewhat experimental; - syntax can change over time without a major bump)" +
             "E.g. to flag modules that are used only once or not at all, use 2 here.",
           minimum: 0,
           maximum: 100,
@@ -248,7 +247,6 @@ export default {
             "Matches when the number of times the 'to' module is used raises above (>) " +
             "this number. Caveat: only works in concert with path and pathNot restrictions " +
             "in the from and to parts of the rule; other conditions will be ignored." +
-            "(somewhat experimental; - syntax can change over time without a major bump)" +
             "E.g. to flag modules that are used more than 10 times, use 10 here.",
           minimum: 0,
           maximum: 100,

tools/schema/rule-set.mjs

@@ -141,13 +141,10 @@ export default {
           description:
             "What to apply the rule to - modules (the default) or folders. Switching " +
             "the scope to 'folder' can be useful in rules where this makes a difference " +
-            "like those regarding circular dependencies or instability. Two things " +
-            "to note when you decide to use 'folder' level scope: (1) the 'scope' attribute " +
-            "is experimental - the way to indicate the scope of a rule can change " +
-            "over time without dependency-cruiser undergoing a major bump. (2) Only " +
-            "the to.moreUnstable, to.circular, and path (both from and to) attributes " +
-            "work at the moment. Other attributes will follow suit in releases " +
-            "after 11.6.0.",
+            "like those regarding circular dependencies or instability. " +
+            "Only the to.moreUnstable, to.circular, and path (both from and to) " +
+            "attributes work at the moment. Other attributes will follow suit " +
+            "in later releases (depending on demand).",
           enum: ["module", "folder"],
         },
         comment: {