@enhance-eng/archangel 0.1.1 → 0.3.0

package/README.md

@@ -4,8 +4,8 @@
 
 ![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)
 
-Architecture tests for TypeScript, checked in milliseconds. You write down how your code is
-organized. Archangel tells you when the code breaks those rules, and what to do about it. It checks
+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
 a large repository in about a second, so it can run in your editor as you type.
 
 ```sh
@@ -18,7 +18,7 @@ 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.
 
-- [Quick start](https://github.com/enhance-labs-builds/archangel/blob/main/README.md#quick-start)
+- [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)

package/archangel.schema.json

@@ -5,14 +5,32 @@
   "description": "The elements of a repository, named sets of its files, and the rules between them. Archangel checks the same fields, with every problem at once.",
   "type": "object",
   "additionalProperties": false,
-  "required": [
-    "elements"
-  ],
   "properties": {
     "$schema": {
       "type": "string",
       "description": "This schema, for editors; archangel ignores it."
     },
+    "parts": {
+      "type": "object",
+      "description": "The parts of the code, by file pattern. A file is in one part at most.",
+      "minProperties": 1,
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "string",
+            "description": "A path pattern; `{name}` captures one instance, such as one feature."
+          },
+          {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1,
+            "description": "Several path patterns."
+          }
+        ]
+      }
+    },
     "elements": {
       "type": "object",
       "description": "The elements: parts of the code by file pattern, or packages, by name.",
@@ -51,6 +69,13 @@
         ]
       }
     },
+    "groups": {
+      "type": "object",
+      "description": "The same as `selectors`: named sets of files, which may overlap.",
+      "additionalProperties": {
+        "$ref": "#/definitions/selector"
+      }
+    },
     "selectors": {
       "type": "object",
       "description": "Named sets of files, which rules and other selectors use by name. A selector's name may not be an element's.",
@@ -58,6 +83,18 @@
         "$ref": "#/definitions/selector"
       }
     },
+    "externals": {
+      "type": "object",
+      "description": "Named lists of outside packages, such as `pg`, `@aws-sdk/*` or `node:fs`.",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "minItems": 1,
+        "description": "Package names. A package is in every set that lists it."
+      }
+    },
     "rules": {
       "type": "array",
       "description": "The rules: a shorthand with `kind`, or a sentence of `files` and one condition.",
@@ -83,6 +120,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -129,6 +170,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -172,6 +217,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -203,6 +252,116 @@
               }
             }
           },
+          {
+            "type": "object",
+            "description": "An import table: for each row, what its files may import. Each row is a rule named `<table>.<row>`.",
+            "additionalProperties": false,
+            "required": [
+              "kind",
+              "name",
+              "rows"
+            ],
+            "properties": {
+              "kind": {
+                "const": "mayImport"
+              },
+              "name": {
+                "type": "string",
+                "description": "The table's name, which starts the name of each row. It has no colon and no slash."
+              },
+              "rows": {
+                "type": "object",
+                "description": "Each row: a part, a group or a kind, and what its files may import.",
+                "additionalProperties": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Names of rows, parts, groups and externals sets, or path patterns."
+                }
+              },
+              "files": {
+                "$ref": "#/definitions/selector",
+                "description": "The files whose imports the table judges. By default, the files of its rows."
+              },
+              "kinds": {
+                "type": "string",
+                "description": "The pattern that gives each file its kind, with the capture `{kind}`."
+              },
+              "within": {
+                "$ref": "#/definitions/side",
+                "description": "An area: the rows judge only imports whose target is in it."
+              },
+              "everyRowMayImport": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Cells that every row also has."
+              },
+              "mayNotImportItself": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "The rows that do not permit their own name."
+              },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
+              "reason": {
+                "type": "string",
+                "description": "Why the rule exists, shown with each violation."
+              },
+              "link": {
+                "type": "string",
+                "description": "Where to read more, shown with each violation."
+              },
+              "imports": {
+                "enum": [
+                  "all",
+                  "runtime",
+                  "types"
+                ],
+                "description": "Which imports the rule checks: all of them, those that stay at runtime, or type imports."
+              },
+              "names": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "minItems": 1,
+                "description": "Only imports that bring in one of these names."
+              },
+              "specifier": {
+                "enum": [
+                  "relative",
+                  "parent",
+                  "alias",
+                  "package"
+                ],
+                "description": "Only imports whose specifier is written this way."
+              },
+              "dependency": {
+                "enum": [
+                  "dev",
+                  "undeclared"
+                ],
+                "description": "Only imports of packages that the nearest package.json lists this way."
+              },
+              "instance": {
+                "enum": [
+                  "same",
+                  "different"
+                ],
+                "description": "Only imports whose two ends compare this way, in the row's name."
+              },
+              "examples": {
+                "$ref": "#/definitions/examples"
+              }
+            }
+          },
           {
             "type": "object",
             "description": "The files may not import the other side.",
@@ -224,6 +383,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -342,6 +505,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -358,8 +525,16 @@
                 "$ref": "#/definitions/examples"
               },
               "mayOnlyImport": {
-                "$ref": "#/definitions/side",
-                "description": "All that the files may import, besides each other."
+                "anyOf": [
+                  {
+                    "$ref": "#/definitions/side"
+                  },
+                  {
+                    "type": "array",
+                    "maxItems": 0
+                  }
+                ],
+                "description": "All that the files may import, besides each other. An empty list needs `within`."
               },
               "names": {
                 "type": "array",
@@ -392,6 +567,10 @@
                   "undeclared"
                 ],
                 "description": "Only imports of packages that the importing file's nearest package.json lists only as development dependencies, or does not list at all."
+              },
+              "within": {
+                "$ref": "#/definitions/side",
+                "description": "The area: only imports whose other end is in it. On `mayOnlyImport` the target, and on `mayOnlyBeImportedBy` the importer."
               }
             }
           },
@@ -416,6 +595,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -466,6 +649,10 @@
                   "undeclared"
                 ],
                 "description": "Only imports of packages that the importing file's nearest package.json lists only as development dependencies, or does not list at all."
+              },
+              "within": {
+                "$ref": "#/definitions/side",
+                "description": "The area: only imports whose other end is in it. On `mayOnlyImport` the target, and on `mayOnlyBeImportedBy` the importer."
               }
             }
           },
@@ -490,6 +677,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -504,9 +695,12 @@
                   },
                   {
                     "$ref": "#/definitions/namePattern"
+                  },
+                  {
+                    "$ref": "#/definitions/nameList"
                   }
                 ],
-                "description": "A style that the name, up to the first dot, must be in, or a name pattern that the full name, without the last extension, must match."
+                "description": "A style that the name, up to the first dot, must be in, or a name pattern that the full name, without the last extension, must match, or a list of them, of which one must match."
               }
             }
           },
@@ -544,6 +738,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -558,9 +756,12 @@
                   },
                   {
                     "$ref": "#/definitions/namePattern"
+                  },
+                  {
+                    "$ref": "#/definitions/nameList"
                   }
                 ],
-                "description": "A style that each folder's name must be in, or a name pattern that it must match, which may use `{FolderName}` for the folder that holds it."
+                "description": "A style that each folder's name must be in, or a name pattern that it must match, which may use `{FolderName}` for the folder that holds it, or a list of them, of which one must match."
               }
             }
           },
@@ -585,6 +786,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -645,6 +850,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -692,6 +901,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -739,6 +952,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -773,6 +990,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -807,6 +1028,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -851,6 +1076,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -885,6 +1114,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -923,6 +1156,10 @@
                 "type": "string",
                 "description": "Why the rule exists, shown with each violation."
               },
+              "because": {
+                "type": "string",
+                "description": "The same as `reason`: why the rule exists. A rule has one of the two."
+              },
               "link": {
                 "type": "string",
                 "description": "Where to read more, shown with each violation."
@@ -1000,13 +1237,29 @@
         "accepted": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/exampleFiles"
+            "anyOf": [
+              {
+                "type": "string",
+                "description": "One line, such as `src/a.ts imports src/b.ts`, for which archangel writes the files."
+              },
+              {
+                "$ref": "#/definitions/exampleFiles"
+              }
+            ]
           }
         },
         "rejected": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/exampleFiles"
+            "anyOf": [
+              {
+                "type": "string",
+                "description": "One line, such as `src/a.ts imports src/b.ts`, for which archangel writes the files."
+              },
+              {
+                "$ref": "#/definitions/exampleFiles"
+              }
+            ]
           }
         }
       }
@@ -1186,7 +1439,51 @@
     "namePattern": {
       "type": "string",
       "minLength": 1,
-      "description": "A name: text, `*` for any text, and `{FileName}`, `{fileName}`, `{file-name}`, `{file_name}` or `{FILE_NAME}` for the file's name in each style, or the same spellings of `{FolderName}` for the name of the folder that holds it."
+      "description": "A name: text, `*` for any text or no text, and `{FileName}`, `{fileName}`, `{file-name}`, `{file_name}` or `{FILE_NAME}` for the file's name in each style, or the same spellings of `{FolderName}` for the name of the folder that holds it."
+    },
+    "nameList": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "anyOf": [
+          {
+            "$ref": "#/definitions/style"
+          },
+          {
+            "$ref": "#/definitions/namePattern"
+          }
+        ]
+      },
+      "description": "The names that a `mustBeNamed` rule permits. One entry must match."
+    }
+  },
+  "anyOf": [
+    {
+      "properties": {
+        "parts": true
+      },
+      "required": [
+        "parts"
+      ]
+    },
+    {
+      "properties": {
+        "elements": true
+      },
+      "required": [
+        "elements"
+      ]
+    },
+    {
+      "properties": {
+        "rules": {
+          "type": "array",
+          "minItems": 1
+        }
+      },
+      "required": [
+        "rules"
+      ]
     }
-  }
+  ]
 }

package/index.d.ts

@@ -1,7 +1,9 @@
 // The types of an archangel config. They check, as the config is written, that every rule names a
-// declared element or selector, that a sentence has exactly one condition, and that an isolate
-// rule names an element with a capture such as `{feature}`. The names inside `selectors` are
-// left to archangel, because checking them here makes TypeScript infer mutable lists for them.
+// declared part or group, that a sentence has exactly one condition, that a table's cells name
+// something, and that an isolate rule names a part with a capture such as `{feature}`. The names
+// inside `groups` are left to archangel, because checking them here makes TypeScript infer mutable
+// lists for them. `parts` and `elements` are two spellings of one key, as are `groups` and
+// `selectors`, and `because` and `reason`: a config uses one spelling of each.
 
 import type { AnyCondition, Plugin } from './plugin.js';
 
@@ -29,6 +31,14 @@ type Captures<S> = S extends string
       : false
     : false;
 
+/** The named sets of outside packages. */
+export type Externals = Readonly<Record<string, readonly string[]>>;
+
+/** Each externals set, as the package element it reads as. */
+type ExternalElements<X extends Externals> = {
+  readonly [K in keyof X]: { readonly packages: readonly string[] };
+};
+
 /** The name of a declared element. */
 export type ElementName<E extends Elements> = Extract<keyof E, string>;
 
@@ -99,21 +109,35 @@ export type Side<E extends Elements, S extends Selectors> =
 /** Files by path, relative to the config folder, with their text. */
 export type ExampleFiles = Readonly<Record<string, string>>;
 
-/** What every rule may have. */
-export interface RuleOptions {
+/** A one-line example, such as `'src/a.ts imports src/b.ts'`, or the files of an example. */
+export type Example = string | ExampleFiles;
+
+/** What the examples of a rule hold. */
+export interface Examples {
+  /** Examples that the rule must accept. */
+  readonly accepted?: readonly Example[];
+  /** Examples that the rule must reject. */
+  readonly rejected?: readonly Example[];
+}
+
+/** Why a rule exists, shown with each violation. A rule has one of the two spellings. */
+type Because =
+  | { readonly because?: string; readonly reason?: never }
+  | { readonly reason?: string; readonly because?: never };
+
+/** What every rule may have, and its reason. */
+export type RuleOptions = CommonOptions & Because;
+
+/** What every rule may have, without its reason. */
+export interface CommonOptions {
   /** The rule's name, for exceptions and the baseline; each rule gives a default. */
   readonly name?: string;
-  /** Why the rule exists, shown with each violation. */
-  readonly reason?: string;
   /** 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';
-  /** File sets the rule must accept and must reject, which `archangel test` checks. */
-  readonly examples?: {
-    readonly accepted?: readonly ExampleFiles[];
-    readonly rejected?: readonly ExampleFiles[];
-  };
+  /** Examples that the rule must accept and must reject, which `archangel test` checks. */
+  readonly examples?: Examples;
 }
 
 /**
@@ -153,12 +177,15 @@ export interface ImportLimits {
 export type NameStyle = 'kebab-case' | 'camelCase' | 'PascalCase' | 'snake_case' | 'SCREAMING_SNAKE_CASE';
 
 /**
- * A name: text, `*` for any text, and `{FileName}`, `{fileName}`, `{file-name}`, `{file_name}` or
+ * A name: text, `*` for any text or no text, and `{FileName}`, `{fileName}`, `{file-name}`, `{file_name}` or
  * `{FILE_NAME}` for the file's name in each style, or the same spellings of `{FolderName}` for the
  * name of the folder that holds it.
  */
 export type NamePattern = string;
 
+/** One name that a `mustBeNamed` rule permits: a style or a name pattern. */
+export type NameEntry = NameStyle | (NamePattern & {});
+
 type Conditions<Other> = {
   /** The files may not import the other side. */
   readonly mayNotImport: Other;
@@ -168,9 +195,9 @@ type Conditions<Other> = {
   readonly mayOnlyBeImportedBy: Other;
   /**
    * The name, up to the first dot, is in a style, or the full name, without the last extension,
-   * matches a name pattern.
+   * matches a name pattern. In a list, one entry must match.
    */
-  readonly mustBeNamed: NameStyle | (NamePattern & {});
+  readonly mustBeNamed: NameEntry | readonly [NameEntry, ...NameEntry[]];
   /**
    * Each instance of `files`, an element with a capture, has a file that matches the pattern, or
    * one of the patterns.
@@ -197,15 +224,21 @@ type NoLimits = { readonly [K in keyof ImportLimits]?: never };
 
 type NoChains = { readonly transitively?: false; readonly stopAt?: never };
 
+type NoArea = { readonly within?: never };
+
+/** The area whose imports an import condition judges: an import outside it passes the rule. */
+type Area<E extends Elements, S extends Selectors> = { readonly within?: Side<E, S> };
+
 /** A rule written as a sentence: `files`, and exactly one condition. */
-export type Sentence<E extends Elements, S extends Selectors> = Omit<RuleOptions, 'imports'> & {
+export type Sentence<E extends Elements, S extends Selectors> = Omit<CommonOptions, 'imports'> & Because & {
   readonly kind?: never;
   /** The files the rule is about. */
   readonly files: Files<E, S>;
 } & (
-    | (Only<Side<E, S>, 'mayNotImport'> & ImportLimits & NoChains & Pick<RuleOptions, 'imports'>)
+    | (Only<Side<E, S>, 'mayNotImport'> & ImportLimits & NoChains & NoArea & Pick<CommonOptions, 'imports'>)
     | (Only<Side<E, S>, 'mayNotImport'> &
-        NoLimits & {
+        NoLimits &
+        NoArea & {
           /** Follow chains of imports, not only direct ones. */
           readonly transitively: true;
           /** Files where a chain ends, such as `{ directive: 'use server' }`. */
@@ -213,24 +246,25 @@ export type Sentence<E extends Elements, S extends Selectors> = Omit<RuleOptions
           /** A chain of type imports never runs, so a transitive rule checks no type imports. */
           readonly imports?: 'all' | 'runtime';
         })
-    | (Only<Side<E, S>, 'mayOnlyImport'> & ImportLimits & NoChains & Pick<RuleOptions, 'imports'>)
+    | (Only<Side<E, S>, 'mayOnlyImport'> & ImportLimits & NoChains & Area<E, S> & Pick<CommonOptions, 'imports'>)
     | (Only<Side<E, S>, 'mayOnlyBeImportedBy'> &
         ImportLimits &
         NoChains &
-        Pick<RuleOptions, 'imports'>)
-    | (Only<Side<E, S>, 'mustBeNamed'> & NoLimits & NoChains & NoImports)
-    | (Only<Side<E, S>, 'mustContain'> & NoLimits & NoChains & NoImports)
-    | (Only<Side<E, S>, 'mustNotExist'> & NoLimits & NoChains & NoImports)
-    | (Only<Side<E, S>, 'mustExport'> & NoLimits & NoChains & NoImports)
-    | (Only<Side<E, S>, 'mayNotExport'> & NoLimits & NoChains & NoImports)
-    | (Only<Side<E, S>, 'mustOnlyReExport'> & NoLimits & NoChains & NoImports)
-    | (Only<Side<E, S>, 'noCycles'> & NoLimits & NoChains & Pick<RuleOptions, 'imports'>)
+        Area<E, S> &
+        Pick<CommonOptions, 'imports'>)
+    | (Only<Side<E, S>, 'mustBeNamed'> & NoLimits & NoChains & NoArea & NoImports)
+    | (Only<Side<E, S>, 'mustContain'> & NoLimits & NoChains & NoArea & NoImports)
+    | (Only<Side<E, S>, 'mustNotExist'> & NoLimits & NoChains & NoArea & NoImports)
+    | (Only<Side<E, S>, 'mustExport'> & NoLimits & NoChains & NoArea & NoImports)
+    | (Only<Side<E, S>, 'mayNotExport'> & NoLimits & NoChains & NoArea & NoImports)
+    | (Only<Side<E, S>, 'mustOnlyReExport'> & NoLimits & NoChains & NoArea & NoImports)
+    | (Only<Side<E, S>, 'noCycles'> & NoLimits & NoChains & NoArea & Pick<CommonOptions, 'imports'>)
   );
 
 type NoImports = { readonly imports?: never };
 
 /** A rule about folders: `folders`, and `mustBeNamed` or `mustContain`. */
-export type FolderSentence = Omit<RuleOptions, 'imports'> & {
+export type FolderSentence = Omit<CommonOptions, 'imports'> & Because & {
   readonly kind?: never;
   readonly files?: never;
   /**
@@ -241,6 +275,7 @@ export type FolderSentence = Omit<RuleOptions, 'imports'> & {
   readonly folders: string | readonly string[];
 } & NoLimits &
   NoChains &
+  NoArea &
   NoImports &
   (
     | (Only<never, 'mustBeNamed'>)
@@ -249,7 +284,7 @@ export type FolderSentence = Omit<RuleOptions, 'imports'> & {
   );
 
 /** A sentence of a rule of several sentences: the rule holds its name, reason and examples. */
-type InnerSentence<T> = T extends unknown ? Omit<T, 'name' | 'reason' | 'link' | 'examples' | 'imports'> : never;
+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> =
@@ -258,7 +293,7 @@ type InnerShorthand<E extends Elements> =
   | { readonly kind: 'entry'; readonly element: NoInfer<ElementName<E>>; readonly files: readonly string[] };
 
 /** A rule of several sentences, broken when any of them is, which needs a name. */
-export type SeveralSentences<E extends Elements, S extends Selectors> = Omit<RuleOptions, 'name'> & {
+export type SeveralSentences<E extends Elements, S extends Selectors> = Omit<CommonOptions, 'name'> & Because & {
   readonly kind?: never;
   readonly files?: never;
   /** The rule's name, for exceptions and the baseline. */
@@ -279,21 +314,95 @@ export type ConditionName<P extends Plugins> = {
     : never;
 }[Extract<keyof P, string>];
 
+/** The conditions of the `fsd` preset, which a config that extends it can use with its own files. */
+export type FsdConditionName = `fsd/${
+  | 'typo-in-layer-name'
+  | 'ambiguous-slice-names'
+  | 'inconsistent-naming'
+  | 'insignificant-slice'
+  | 'repetitive-naming'
+  | 'excessive-slicing'
+  | 'shared-lib-grouping'}`;
+
 /** A rule that uses a plugin's condition, whose options the condition's schema checks. */
 export type PluginRule<E extends Elements, S extends Selectors, P extends Plugins> = Omit<
-  RuleOptions,
+  CommonOptions,
   'imports'
-> & {
+> & Because & NoArea & {
   readonly kind?: never;
   /** The files whose records the condition sees. */
   readonly files: Files<E, S>;
   /** The condition, as `<plugin>/<condition>`. */
-  readonly plugin: NoInfer<ConditionName<P>>;
+  readonly plugin: NoInfer<ConditionName<P>> | FsdConditionName;
   /** The options, which the condition's JSON Schema checks when the config loads. */
   readonly options?: unknown;
 };
 
-/** A rule, as an object: one of the three shorthands, a sentence, or a plugin rule. */
+/** A word for a table or a row: any text with no colon and no slash. */
+type NoSeparator<T extends string> = T extends `${string}:${string}` | `${string}/${string}`
+  ? 'the name of a table or a row has no colon or slash'
+  : T;
+
+/** The name of a table. */
+export type TableName<T extends string> = NoSeparator<T>;
+
+/** What a table's rows are, before their names are checked. */
+export type TableRows = Readonly<Record<string, readonly string[]>>;
+
+/** What a cell may name: a row, a declared name, or a path pattern. */
+type TableCell<Row extends string, Declared extends string> = Row | Declared | PathPattern;
+
+/**
+ * The rows `R`, with each cell checked, and each row name checked against `Key`, the row names that
+ * the table permits.
+ */
+type CheckedRows<R extends TableRows, Key extends string, Declared extends string> = {
+  readonly [Row in keyof R]: Row extends string
+    ? Row extends NoSeparator<Row>
+      ? Row extends Key
+        ? readonly TableCell<Extract<keyof R, string>, Declared>[]
+        : 'a row of a table without kinds is a declared part or group'
+      : NoSeparator<Row>
+    : never;
+};
+
+/** A name that a table can use as a row without kinds: a part or a group, not a set of packages. */
+type RowName<E extends Elements, S extends Selectors> = FileElementName<E> | Extract<keyof S, string>;
+
+/** Every name that a cell can use. */
+type DeclaredName<E extends Elements, S extends Selectors> = ElementName<E> | Extract<keyof S, string>;
+
+/** The options of a table with the rows `R`. */
+export type TableOptions<E extends Elements, S extends Selectors, Row extends string> = Omit<CommonOptions, 'name'> &
+  Because &
+  ImportLimits & {
+    /** The files that the table judges as importers; without it, every file with a row. */
+    readonly files?: Files<E, S>;
+    /** The area whose imports the table judges, and without it, the whole repository. */
+    readonly within?: Side<E, S>;
+    /** Cells that every row has, such as a file that all code may use. */
+    readonly everyRowMayImport?: readonly TableCell<NoInfer<Row>, DeclaredName<E, S>>[];
+    /** Rows that may not import their own name, in the same instance or in another. */
+    readonly mayNotImportItself?: readonly NoInfer<Row>[];
+  };
+
+/** A table, as an object. Archangel checks its names when the config loads. */
+export type TableRule = RuleOptions &
+  ImportLimits & {
+    readonly kind: 'mayImport';
+    readonly name: string;
+    readonly rows: TableRows;
+    readonly kinds?: string;
+    readonly files?: unknown;
+    readonly within?: unknown;
+    readonly everyRowMayImport?: readonly string[];
+    readonly mayNotImportItself?: readonly string[];
+  };
+
+/** A rule's body when its name comes first. */
+type Body<T> = T extends unknown ? Omit<T, 'name'> & { readonly name?: never } : 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: 'isolate'; readonly element: NoInfer<CapturedElement<E>> })
@@ -302,6 +411,7 @@ export type Rule<E extends Elements, S extends Selectors = {}, P extends Plugins
       readonly element: NoInfer<ElementName<E>>;
       readonly files: readonly string[];
     })
+  | TableRule
   | Sentence<E, S>
   | FolderSentence
   | SeveralSentences<E, S>
@@ -333,6 +443,26 @@ export interface RuleBuilders<
     files: string | readonly string[],
     options?: RuleOptions & Named<N, X>,
   ): Rule<E, S, P>;
+  /** A table of what each row may import, whose rows are kinds of file, parts or groups. */
+  mayImport<const T extends string, const R extends TableRows>(
+    name: TableName<T>,
+    rows: R & CheckedRows<R, string, DeclaredName<E, S>>,
+    options: TableOptions<E, S, Extract<keyof R, string>> & {
+      /** The pattern that gives a file its kind, such as `**\/*.{kind}.ts`. */
+      readonly kinds: string;
+    },
+  ): Rule<E, S, P>;
+  /** A table whose rows are all parts or groups. */
+  mayImport<const T extends string, const R extends TableRows>(
+    name: TableName<T>,
+    rows: R & CheckedRows<R, RowName<E, S>, DeclaredName<E, S>>,
+    options?: TableOptions<E, S, Extract<keyof R, string>> & { readonly kinds?: never },
+  ): Rule<E, S, P>;
+  /** A rule with its name first: `files`, or `folders`, and exactly one condition. */
+  rule<const N extends string = string>(
+    name: OwnRuleName<N, X>,
+    sentence: Body<Sentence<E, S> | FolderSentence | SeveralSentences<E, S> | PluginRule<E, S, P>>,
+  ): Rule<E, S, P>;
   /** A rule as a sentence: `files`, or `folders`, and exactly one condition or plugin condition. */
   rule<const N extends string = string>(
     sentence: (Sentence<E, S> | FolderSentence | SeveralSentences<E, S> | PluginRule<E, S, P>) &
@@ -351,8 +481,11 @@ export interface Preset<X extends string = string> {
   readonly package?: string;
   /** The folder the preset applies to, relative to the config folder. */
   readonly root?: string;
+  readonly parts?: Elements;
   readonly elements?: Elements;
+  readonly groups?: Selectors;
   readonly selectors?: Selectors;
+  readonly externals?: Externals;
   readonly plugins?: Plugins;
   /** The rules, each with a name. */
   readonly rules?: readonly unknown[] | ((builders: RuleBuilders<Elements, Selectors, Plugins>) => readonly unknown[]);
@@ -377,36 +510,65 @@ export declare function nextjs<const X extends string = 'nextjs'>(options?: {
   readonly root?: string;
 }): Preset<X>;
 
+/** The parts of the code, by file pattern. A part holds files, so it has no packages. */
+export type PartSpecs = Readonly<Record<string, string | readonly string[]>>;
+
+/** One spelling of the parts of the code. */
+type PartsKey<E extends Elements> =
+  | {
+      /** The parts of the code, by file pattern. Each file is in one part. */
+      readonly parts?: E & PartSpecs;
+      readonly elements?: never;
+    }
+  | {
+      /** The same as `parts`, which may also hold packages. */
+      readonly elements?: E;
+      readonly parts?: never;
+    };
+
+/** One spelling of the named sets of files. */
+type GroupsKey<S extends Selectors> =
+  | {
+      /** Named sets of files, which can cross parts, and which rules use by name. */
+      readonly groups?: S;
+      readonly selectors?: never;
+    }
+  | {
+      /** The same as `groups`. */
+      readonly selectors?: S;
+      readonly groups?: never;
+    };
+
 /**
- * An archangel config, which extends the presets named in `X` and names its own rules with the
- * names in `N`.
+ * An archangel config, which extends the presets named in `X`, names its own rules with the names
+ * in `N`, and names the sets of outside packages in `O`.
  */
-export interface Config<
+export type Config<
   E extends Elements,
   S extends Selectors = {},
   P extends Plugins = {},
   X extends string = string,
   N extends string = string,
-> {
-  /** The elements: parts of the code by file pattern, or packages; a config that extends a preset may have none. */
-  readonly elements?: E;
-  /** Named sets of files, which rules and other selectors use by name. */
-  readonly selectors?: S;
-  /** Lines in `.gitignore` syntax that remove files from the check. */
-  readonly ignore?: readonly string[];
-  /** Specifiers that may stay unresolved, each with the reason; a specifier may end in `*`. */
-  readonly allowUnresolved?: Readonly<Record<string, string>>;
-  /** The plugins, by the name the rules use them by, as `plugin: '<name>/<condition>'`. */
-  readonly plugins?: P;
-  /** The presets the config extends; the config's own rules replace preset rules of one name. */
-  readonly extends?: readonly Preset<X>[];
-  /** Rule names to turn off after the presets are merged, such as `fsd/insignificant-slice`. */
-  readonly off?: readonly string[];
-  /** The rules, or a function that builds them. */
-  readonly rules:
-    | readonly (Rule<E, S, P> & Named<N, X>)[]
-    | ((builders: RuleBuilders<E, S, P, X>) => readonly (Rule<E, S, P> & Named<N, X>)[]);
-}
+  O extends Externals = {},
+> = PartsKey<E> &
+  GroupsKey<S> & {
+    /** Named sets of outside packages, such as `{ driver: ['pg', '@aws-sdk/*', 'node:fs'] }`. */
+    readonly externals?: O;
+    /** Lines in `.gitignore` syntax that remove files from the check. */
+    readonly ignore?: readonly string[];
+    /** Specifiers that may stay unresolved, each with the reason; a specifier may end in `*`. */
+    readonly allowUnresolved?: Readonly<Record<string, string>>;
+    /** The plugins, by the name the rules use them by, as `plugin: '<name>/<condition>'`. */
+    readonly plugins?: P;
+    /** The presets the config extends; the config's own rules replace preset rules of one name. */
+    readonly extends?: readonly Preset<X>[];
+    /** Rule or table names to turn off after the presets are merged, such as `fsd/insignificant-slice`. */
+    readonly off?: readonly string[];
+    /** The rules, or a function that builds them. */
+    readonly rules?:
+      | readonly (Rule<E & ExternalElements<O>, S, P> & Named<N, X>)[]
+      | ((builders: RuleBuilders<E & ExternalElements<O>, S, P, X>) => readonly (Rule<E & ExternalElements<O>, S, P> & Named<N, X>)[]);
+  };
 
 /** Declares an archangel config, with types that check its names as it is written. */
 export declare function defineConfig<
@@ -415,4 +577,5 @@ export declare function defineConfig<
   const P extends Plugins = {},
   const X extends string = never,
   const N extends string = string,
->(config: Config<E, S, P, X, N>): Config<E, S, P>;
+  const O extends Externals = {},
+>(config: Config<E, S, P, X, N, O>): Config<E, S, P, string, string, O>;

package/package.json

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