@enhance-eng/archangel 0.3.3 → 0.3.4

package/README.md

@@ -2,7 +2,9 @@
 
 **Make architecture verifiable.**
 
-![Seconds to check the same 400 architecture rules on a 9,800-file TypeScript monorepo: archangel 1.9 s; dependency-cruiser, ESLint and Steiger together 67.7 s](https://raw.githubusercontent.com/enhance-labs-builds/archangel/main/docs/assets/speed-light.svg)
+### [Read the docs →](https://enhancelabs.ai/archangel/)
+
+![Seconds to check the same 400 architecture rules on a 9,800-file TypeScript monorepo: archangel 1.9 s; dependency-cruiser, ESLint and Steiger together 67.7 s](https://raw.githubusercontent.com/enhance-labs-builds/archangel/main/.github/assets/speed-light.svg)
 
 Architecture tests for TypeScript, checked in milliseconds. You write a table of what each part of
 your code may import. Archangel tells you when the code breaks the table, and what to do about it. It checks
@@ -18,11 +20,10 @@ Archangel checks imports, import cycles, file and folder names, the files that f
 and exports. It has presets for Feature-Sliced Design and Next.js, and you can write your own
 conditions in TypeScript.
 
-- [Get started](https://github.com/enhance-labs-builds/archangel/blob/main/README.md#get-started)
-- [Rules](https://github.com/enhance-labs-builds/archangel/blob/main/docs/rules.md)
-- [Presets](https://github.com/enhance-labs-builds/archangel/blob/main/docs/presets.md)
-- [Plugins](https://github.com/enhance-labs-builds/archangel/blob/main/docs/plugins.md)
-- [Commands](https://github.com/enhance-labs-builds/archangel/blob/main/docs/commands.md)
+- [Getting started](https://enhancelabs.ai/archangel/start/getting-started/)
+- [Guides](https://enhancelabs.ai/archangel/guides/existing-repository/)
+- [Reference](https://enhancelabs.ai/archangel/reference/conditions/)
+- [Docs for coding agents](https://enhancelabs.ai/archangel/llms.txt)
 
 The package includes a prebuilt binary for macOS, Linux and Windows. You do not need Rust.
 

package/archangel.schema.json

@@ -102,7 +102,7 @@
         "oneOf": [
           {
             "type": "object",
-            "description": "Each listed element may import only itself and later listed elements.",
+            "description": "Each listed part or group may import only itself and later listed ones.",
             "additionalProperties": false,
             "required": [
               "kind",
@@ -132,9 +132,10 @@
                 "enum": [
                   "all",
                   "runtime",
+                  "static",
                   "types"
                 ],
-                "description": "Which imports the rule checks: all of them, those that stay at runtime, or type imports."
+                "description": "Which imports the rule checks: all of them, those that stay at runtime, the runtime imports other than `import()`, or type imports."
               },
               "examples": {
                 "$ref": "#/definitions/examples"
@@ -146,7 +147,7 @@
                   "minLength": 1
                 },
                 "minItems": 1,
-                "description": "Each listed element may import only itself and later listed elements."
+                "description": "Each listed part or group may import only itself and later listed ones."
               }
             }
           },
@@ -182,9 +183,10 @@
                 "enum": [
                   "all",
                   "runtime",
+                  "static",
                   "types"
                 ],
-                "description": "Which imports the rule checks: all of them, those that stay at runtime, or type imports."
+                "description": "Which imports the rule checks: all of them, those that stay at runtime, the runtime imports other than `import()`, or type imports."
               },
               "examples": {
                 "$ref": "#/definitions/examples"
@@ -229,9 +231,10 @@
                 "enum": [
                   "all",
                   "runtime",
+                  "static",
                   "types"
                 ],
-                "description": "Which imports the rule checks: all of them, those that stay at runtime, or type imports."
+                "description": "Which imports the rule checks: all of them, those that stay at runtime, the runtime imports other than `import()`, or type imports."
               },
               "examples": {
                 "$ref": "#/definitions/examples"
@@ -322,9 +325,10 @@
                 "enum": [
                   "all",
                   "runtime",
+                  "static",
                   "types"
                 ],
-                "description": "Which imports the rule checks: all of them, those that stay at runtime, or type imports."
+                "description": "Which imports the rule checks: all of them, those that stay at runtime, the runtime imports other than `import()`, or type imports."
               },
               "names": {
                 "type": "array",
@@ -395,9 +399,10 @@
                 "enum": [
                   "all",
                   "runtime",
+                  "static",
                   "types"
                 ],
-                "description": "Which imports the rule checks: all of them, those that stay at runtime, or type imports."
+                "description": "Which imports the rule checks: all of them, those that stay at runtime, the runtime imports other than `import()`, or type imports."
               },
               "examples": {
                 "$ref": "#/definitions/examples"
@@ -474,7 +479,8 @@
                 "imports": {
                   "enum": [
                     "all",
-                    "runtime"
+                    "runtime",
+                    "static"
                   ]
                 },
                 "names": false,
@@ -517,9 +523,10 @@
                 "enum": [
                   "all",
                   "runtime",
+                  "static",
                   "types"
                 ],
-                "description": "Which imports the rule checks: all of them, those that stay at runtime, or type imports."
+                "description": "Which imports the rule checks: all of them, those that stay at runtime, the runtime imports other than `import()`, or type imports."
               },
               "examples": {
                 "$ref": "#/definitions/examples"
@@ -607,9 +614,10 @@
                 "enum": [
                   "all",
                   "runtime",
+                  "static",
                   "types"
                 ],
-                "description": "Which imports the rule checks: all of them, those that stay at runtime, or type imports."
+                "description": "Which imports the rule checks: all of them, those that stay at runtime, the runtime imports other than `import()`, or type imports."
               },
               "examples": {
                 "$ref": "#/definitions/examples"
@@ -1126,9 +1134,10 @@
                 "enum": [
                   "all",
                   "runtime",
+                  "static",
                   "types"
                 ],
-                "description": "Which imports the rule checks: all of them, those that stay at runtime, or type imports."
+                "description": "Which imports the rule checks: all of them, those that stay at runtime, the runtime imports other than `import()`, or type imports."
               },
               "examples": {
                 "$ref": "#/definitions/examples"
@@ -1168,9 +1177,10 @@
                 "enum": [
                   "all",
                   "runtime",
+                  "static",
                   "types"
                 ],
-                "description": "Which imports the rule's import sentences check: all of them, those that stay at runtime, or type imports."
+                "description": "Which imports the rule's import sentences check: all of them, those that stay at runtime, the runtime imports other than `import()`, or type imports."
               },
               "examples": {
                 "$ref": "#/definitions/examples"
@@ -1379,6 +1389,20 @@
               "description": "The files that start with this directive, such as `use client`."
             }
           }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "tag"
+          ],
+          "properties": {
+            "tag": {
+              "type": "string",
+              "pattern": "^@.",
+              "description": "The files whose comments before the first statement carry this JSDoc tag, such as `@side-effect-free`."
+            }
+          }
         }
       ]
     },

package/index.d.ts

@@ -79,7 +79,9 @@ export type SelectorObject<N extends string, F extends string = N> =
       readonly directive?: never;
     }
   /** The files that start with a directive, such as `'use client'`. */
-  | { readonly directive: string; readonly element?: never };
+  | { readonly directive: string; readonly element?: never; readonly tag?: never }
+  /** The files whose comments before the first statement carry a JSDoc tag, such as `'@side-effect-free'`. */
+  | { readonly tag: `@${string}`; readonly element?: never; readonly directive?: never };
 
 /** The selectors, by name. */
 export type Selectors = Record<string, SelectorDefinition<string>>;
@@ -135,7 +137,8 @@ export interface CommonOptions {
   /** Where to read more, shown with each violation. */
   readonly link?: string;
   /** Which imports the rule checks: all of them, those that stay at runtime, or type imports. */
-  readonly imports?: 'all' | 'runtime' | 'types';
+  /** `'static'` is the runtime imports other than `import()`: a transitive rule then stops at each `import()`. */
+  readonly imports?: 'all' | 'runtime' | 'static' | 'types';
   /** Examples that the rule must accept and must reject, which `archangel test` checks. */
   readonly examples?: Examples;
 }
@@ -244,7 +247,7 @@ export type Sentence<E extends Elements, S extends Selectors> = Omit<CommonOptio
           /** Files where a chain ends, such as `{ directive: 'use server' }`. */
           readonly stopAt?: Files<E, S>;
           /** A chain of type imports never runs, so a transitive rule checks no type imports. */
-          readonly imports?: 'all' | 'runtime';
+          readonly imports?: 'all' | 'runtime' | 'static';
         })
     | (Only<Side<E, S>, 'mayOnlyImport'> & ImportLimits & NoChains & Area<E, S> & Pick<CommonOptions, 'imports'>)
     | (Only<Side<E, S>, 'mayOnlyBeImportedBy'> &
@@ -287,8 +290,8 @@ export type FolderSentence = Omit<CommonOptions, 'imports'> & Because & {
 type InnerSentence<T> = T extends unknown ? Omit<T, 'name' | 'reason' | 'because' | 'link' | 'examples' | 'imports'> : never;
 
 /** A shorthand as one sentence of a rule of several sentences. */
-type InnerShorthand<E extends Elements> =
-  | { readonly kind: 'layers'; readonly order: readonly NoInfer<ElementName<E>>[] }
+type InnerShorthand<E extends Elements, S extends Selectors> =
+  | { readonly kind: 'layers'; readonly order: readonly NoInfer<ElementName<E> | Extract<keyof S, string>>[] }
   | { readonly kind: 'isolate'; readonly element: NoInfer<CapturedElement<E>> }
   | { readonly kind: 'entry'; readonly element: NoInfer<ElementName<E>>; readonly files: readonly string[] };
 
@@ -299,7 +302,7 @@ export type SeveralSentences<E extends Elements, S extends Selectors> = Omit<Com
   /** The rule's name, for exceptions and the baseline. */
   readonly name: string;
   /** The sentences, each about `files` or `folders` with one condition, or a shorthand. */
-  readonly sentences: readonly (InnerSentence<Sentence<E, S> | FolderSentence> | InnerShorthand<E>)[];
+  readonly sentences: readonly (InnerSentence<Sentence<E, S> | FolderSentence> | InnerShorthand<E, S>)[];
 };
 
 /** The plugins a config loads, by the name its rules use them by. */
@@ -404,7 +407,7 @@ type Body<T> = T extends unknown ? Omit<T, 'name'> & { readonly name?: never } :
 
 /** A rule, as an object: one of the three shorthands, a table, a sentence, or a plugin rule. */
 export type Rule<E extends Elements, S extends Selectors = {}, P extends Plugins = {}> =
-  | (RuleOptions & { readonly kind: 'layers'; readonly order: readonly NoInfer<ElementName<E>>[] })
+  | (RuleOptions & { readonly kind: 'layers'; readonly order: readonly NoInfer<ElementName<E> | Extract<keyof S, string>>[] })
   | (RuleOptions & { readonly kind: 'isolate'; readonly element: NoInfer<CapturedElement<E>> })
   | (RuleOptions & {
       readonly kind: 'entry';
@@ -427,9 +430,9 @@ export interface RuleBuilders<
   P extends Plugins = {},
   X extends string = string,
 > {
-  /** Each listed element may import only itself and later listed elements. */
+  /** Each listed element or group may import only itself and later listed ones. */
   readonly layers: <const N extends string = string>(
-    order: readonly NoInfer<ElementName<E>>[],
+    order: readonly NoInfer<ElementName<E> | Extract<keyof S, string>>[],
     options?: RuleOptions & Named<N, X>,
   ) => Rule<E, S, P>;
   /** The instances of the element may not import each other. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enhance-eng/archangel",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Make architecture verifiable. Architecture tests for TypeScript, checked in milliseconds: imports, cycles, names, folder structure and exports.",
   "keywords": [
     "architecture",
@@ -53,13 +53,13 @@
     "pluralize": "8.0.0"
   },
   "optionalDependencies": {
-    "@enhance-eng/archangel-darwin-arm64": "0.3.3",
-    "@enhance-eng/archangel-darwin-x64": "0.3.3",
-    "@enhance-eng/archangel-linux-arm64-gnu": "0.3.3",
-    "@enhance-eng/archangel-linux-arm64-musl": "0.3.3",
-    "@enhance-eng/archangel-linux-x64-gnu": "0.3.3",
-    "@enhance-eng/archangel-linux-x64-musl": "0.3.3",
-    "@enhance-eng/archangel-win32-x64": "0.3.3"
+    "@enhance-eng/archangel-darwin-arm64": "0.3.4",
+    "@enhance-eng/archangel-darwin-x64": "0.3.4",
+    "@enhance-eng/archangel-linux-arm64-gnu": "0.3.4",
+    "@enhance-eng/archangel-linux-arm64-musl": "0.3.4",
+    "@enhance-eng/archangel-linux-x64-gnu": "0.3.4",
+    "@enhance-eng/archangel-linux-x64-musl": "0.3.4",
+    "@enhance-eng/archangel-win32-x64": "0.3.4"
   },
   "tsd": {
     "compilerOptions": {