arkgate 4.8.23 → 4.8.25

package/dist/eslint/index.d.cts

@@ -0,0 +1,368 @@
+import { A as ArkConfig } from '../configTypes-GPvvdleM.cjs';
+
+/**
+ * Pure layer-glob matching for ark.config.json.
+ *
+ * **Canonical algorithm** for CLI, ESLint, and library consumers.
+ * The CLI load path uses the generated `bin/ark-layer-match.mjs`
+ * (`npm run generate:layer-match` / `npm run check:layer-match`).
+ * Behavioral parity tests remain a safety net.
+ */
+type LayerConfig = {
+    name: string;
+    patterns?: string[];
+    exclude?: string[];
+    forbiddenGlobals?: string[];
+};
+/**
+ * How a starred `sliceFolders` prefix becomes a slice id.
+ *
+ * - `path` (default, also the absent value): every literal and every star
+ *   binding. `lib/features` plus two stars → `lib/features/projects/rfi`.
+ *   Byte-identical to the ids baselines and `allowedCrossSlice` already use.
+ * - `stars`: last literal segment plus every star binding (a star before the
+ *   last literal is kept too: `modules` / `*` / `api` / `*` → `orders/api/v1`).
+ *   `lib/features` plus two stars, and `lib/repositories/features` plus two
+ *   stars, both → `features/projects/rfi`.
+ *   Prefix stripping stays inside `bindAnchoredSlice`. Bare names are unchanged.
+ */
+type SliceIdentity = 'path' | 'stars';
+/**
+ * Layer-to-layer dependency rule from ark.config.json.
+ *
+ * - Classic: `{ from, to, allowed: false }` denies **cross-layer** edges only.
+ *   Same-layer is always allowed without peerIsolation (historical short-circuit).
+ * - `peerIsolation: true` + `allowed: false`: deny only when slice ids differ
+ *   (same **or** cross layer). Same-slice → allow. File imports pass fromPath
+ *   and toPath. Intent references pass fromPath only (intents are not files);
+ *   a declared shared root is classified and does not deny. Missing fromPath,
+ *   no slice folders, or unclassifiable slices → fail-closed.
+ */
+type EdgeRule = {
+    from: string;
+    to: string;
+    allowed?: boolean;
+    /**
+     * When true with `allowed: false`: deny only when importer and importee resolve
+     * to different slice ids (parent/name, e.g. features/auth). Works same-layer
+     * and cross-layer. See findDeniedEdgeRule.
+     */
+    peerIsolation?: boolean;
+    /**
+     * Slice parents. A bare name (`["features"]`) is an unanchored one-segment
+     * match: `src/features/auth/api.ts` → `features/auth`. The next segment is
+     * never a filename. A starred prefix (`lib` / `features` / `*` / `*`) is
+     * anchored like `sharedRoots`. With `sliceIdentity` `"path"` (the default,
+     * also when the key is absent) the slice id includes the literal prefix
+     * plus the directories the stars bind (`lib/features/projects/rfi`), so
+     * parallel trees get different ids. With `"stars"` it is the last literal
+     * plus every star binding, so the same feature has one id across parallel
+     * trees.
+     * When omitted, inferred from the layer's glob patterns (segment before a wildcard).
+     */
+    sliceFolders?: string[];
+    /**
+     * How a starred `sliceFolders` prefix is named. Absent and `"path"` keep
+     * today's ids. `"stars"` is the last literal plus every star binding, in
+     * path order (`modules` / `*` / `api` / `*` binds `orders/api/v1`), so the same feature
+     * has one id across parallel trees.
+     */
+    sliceIdentity?: SliceIdentity;
+    /**
+     * Roots the repo declares **shared on purpose** (`["ui", "hooks", "lib/permissions"]`).
+     *
+     * A file under a declared shared root is *evidence*, not an unclassifiable path:
+     * the repo has said this code belongs to no slice, so peerIsolation stops
+     * reporting our inability to place it as a violation of their design.
+     * Matched as a contiguous run of path segments anywhere in the repo-relative
+     * path (so `ui` covers `src/ui/button.tsx`), case-insensitively; a root
+     * containing `*` is matched as a glob. A path that still resolves to a slice
+     * id keeps its slice — a shared root never shadows a real slice.
+     *
+     * Note: this only relaxes the *unclassifiable* branch. A genuine cross-slice
+     * edge between two different slices still denies.
+     */
+    sharedRoots?: string[];
+    /**
+     * Directed cross-slice edges the repo declares on purpose — same shape as the
+     * layer edges in `rules[]`, but between slice ids:
+     * `[{ from: "features/checkout", to: "features/catalog" }]`.
+     *
+     * Each entry allows exactly one direction. Slice ids match either fully
+     * (`features/auth`) or by bare slice name (`auth`), case-insensitively — a bare
+     * name matches that name under *any* slice folder, so write the full id in a repo
+     * with several slice parents. Everything not declared still denies.
+     * `*` is a literal character on this list, not a wildcard.
+     */
+    allowedCrossSlice?: CrossSliceEdge[];
+    /**
+     * `"deny"`: a shared root may not import a slice. `"deny-cross-parent"` leaves
+     * that hop allowed; a whole-graph pass then reports a slice that reaches
+     * another universe only through shared. Absent keeps the hop allowed.
+     * `allowedCrossSlice` does not excuse `"deny"`. The object form
+     * `{ mode: "deny-cross-parent", stopAt }` names composition roots the walk
+     * never starts at or passes through. Read it through
+     * {@link sharedImportsSliceMode} / {@link sharedImportsSliceStopAt}.
+     */
+    sharedImportsSlice?: SharedImportsSliceSetting;
+    /**
+     * Optional inner wall under this rule's universe wall. Absent: the universe
+     * wall is the whole decision and check output stays byte-identical.
+     * Present: a universe cross-slice deny is `CROSS_PARENT_SLICE`. An edge the
+     * universe wall allows may still deny on the child wall.
+     */
+    childSlices?: ChildSlices;
+    /** Optional override message for scanners / write-gate. */
+    message?: string;
+};
+/**
+ * Inner slice wall. `sliceFolders` names children under the universe.
+ * A side with no child id (a flat file, or a `commonFolders` directory) is
+ * universe common. `siblings` is `deny`, `advisory`, or `{ default, enforce }`.
+ * Cross-parent has no knob. `parentMayImportChild` defaults to false.
+ * `allowedCrossSlice` here may use a whole-segment `*`. It clears only a
+ * sibling crossing, and only after the universe wall has allowed the edge.
+ */
+/** A folder outside the slice trees, borrowed onto a child id until it moves. */
+type SliceAlias = {
+    /** Source path glob. Only files the slice folders do not already classify. */
+    from: string;
+    /** Child slice id: the universe id plus one child segment. */
+    to: string;
+    /** True: this path stays. It is listed, and it is not an owed move. */
+    pinned?: boolean;
+    /** Doctor label. A label alone does not pin. */
+    reason?: string;
+};
+type ChildSlices = {
+    sliceFolders: string[];
+    sliceIdentity?: SliceIdentity;
+    commonFolders?: string[];
+    siblings?: ChildSliceSiblings;
+    parentMayImportChild?: boolean;
+    /** Text for inner-wall findings (sibling, common → child). Absent: ArkGate default, never the rule message. */
+    message?: string;
+    /** Directed child allowances. `*` matches one whole segment. Never a universe excuse. */
+    allowedCrossSlice?: CrossSliceEdge[];
+    /** Unclassified files governed as this child. Debt, not a destination. */
+    sliceAliases?: SliceAlias[];
+    /**
+     * Filename read at each child root this wall already resolved.
+     * `<Layer>` is the only token (`arkrules.<Layer>.json`).
+     */
+    arkRulesFile?: string;
+};
+/** How the child wall treats a sibling crossing. Absent means `deny`. */
+type ChildSliceSiblingsMode = 'deny' | 'advisory';
+/**
+ * Per-subtree sibling enforcement. `default` is everyone not listed.
+ * `enforce` names child slice ids or subtree paths. The list never loosens deny.
+ */
+type ChildSliceSiblingsEnforce = {
+    default: ChildSliceSiblingsMode;
+    enforce?: string[];
+    /**
+     * Anti-growth for advisory crossings against a baseline. Absent: on only when
+     * the baseline already records an advisory crossing of this rule. `true`:
+     * always when a baseline is in use. `false`: measure only.
+     */
+    ratchet?: boolean;
+};
+type ChildSliceSiblings = ChildSliceSiblingsMode | ChildSliceSiblingsEnforce;
+/** `sharedImportsSlice` string modes. */
+type SharedImportsSliceMode = 'deny' | 'deny-cross-parent';
+/** String mode, or the object form that carries composition-root stops. */
+type SharedImportsSliceSetting = SharedImportsSliceMode | {
+    mode: 'deny-cross-parent';
+    stopAt: string[];
+};
+/** A directed slice-to-slice edge the repo declares on purpose (peerIsolation). */
+type CrossSliceEdge = {
+    /** Importing slice id (`features/checkout`) or bare slice name (`checkout`). */
+    from: string;
+    /** Imported slice id or bare slice name. */
+    to: string;
+};
+/** Options for path-aware edge checks (peer isolation). */
+type EdgeCheckOptions = {
+    /** Repo-relative path of the importing file. */
+    fromPath?: string;
+    /** Repo-relative path of the imported module. Omit for intent names (not files). */
+    toPath?: string;
+    /** Layer configs — used to infer sliceFolders when the rule omits them. */
+    layers?: LayerConfig[];
+};
+declare function globToRegExp(pattern: string): RegExp;
+/**
+ * Rank competing layer globs.
+ *
+ * Without a path: concrete-segment count + literal length (historical shape).
+ * With a path: last matched concrete segment depth dominates so interior
+ * domain/persistence folders beat Application/Presentation scatter bags
+ * (DL-DOMAIN-SPECIFICITY / NEW-APP-VACUUM-LIB).
+ */
+declare function patternSpecificity(pattern: string, relPath?: string): number;
+declare function layerForRelativePath(relPath: string, layers: LayerConfig[] | undefined): string | undefined;
+declare function isEdgeDenied(rules: EdgeRule[] | undefined, from: string, to: string, options?: EdgeCheckOptions): boolean;
+
+/**
+ * Shared ESLint adapter plumbing: context shapes, filename / source helpers, and the
+ * adapter-diagnostic report path. Channel routing lives in reportChannels.ts.
+ */
+
+type AstNode = {
+    type?: string;
+    name?: string;
+    value?: unknown;
+    source?: AstNode;
+    callee?: AstNode;
+    object?: AstNode;
+    property?: AstNode;
+    key?: AstNode;
+    arguments?: AstNode[];
+    properties?: AstNode[];
+    body?: AstNode[];
+    declaration?: AstNode;
+    importKind?: string;
+    exportKind?: string;
+    specifiers?: AstNode[];
+    parent?: AstNode;
+    init?: AstNode;
+    id?: AstNode;
+    left?: AstNode;
+    argument?: AstNode;
+    expression?: AstNode;
+    quasis?: Array<{
+        value?: {
+            cooked?: string | null;
+        };
+    }>;
+    expressions?: unknown[];
+    computed?: boolean;
+    optional?: boolean;
+    loc?: {
+        start?: {
+            line?: number;
+            column?: number;
+        };
+        end?: {
+            line?: number;
+            column?: number;
+        };
+    };
+};
+type ScopeVariable = {
+    defs?: unknown[];
+};
+type ScopeReference = {
+    identifier?: AstNode;
+    resolved?: ScopeVariable | null;
+    isValueReference?: boolean;
+};
+type Scope = {
+    set?: Map<string, ScopeVariable>;
+    references?: ScopeReference[];
+    upper?: Scope | null;
+};
+type SourceCode = {
+    getScope?: (node: AstNode) => Scope;
+    getText?: () => string;
+    text?: string;
+};
+type RuleContext = {
+    report(descriptor: Record<string, unknown>): void;
+    /** ESLint 9+ / 10: preferred path on the context object. */
+    filename?: string;
+    /** ESLint 8-style physical path when linting with processors / virtual files. */
+    physicalFilename?: string;
+    /** ESLint ≤8 API — still present on some hosts; removed in ESLint 10. */
+    getFilename?: () => string;
+    /** ESLint 9+ source/scope API. */
+    sourceCode?: SourceCode;
+    /** ESLint ≤8 source/scope API. */
+    getSourceCode?: () => SourceCode;
+    options?: unknown[];
+};
+type RuleListener = Record<string, (node: AstNode) => void>;
+type ArkRule = {
+    meta: {
+        type: 'problem';
+        docs: {
+            description: string;
+        };
+        messages: Record<string, string>;
+        schema: unknown[];
+    };
+    create(context: RuleContext): RuleListener;
+};
+
+/** Nearest `ark.config.json` at or above the linted file (memoized per directory). */
+declare function findConfigPath(startFile: string): string | null;
+/**
+ * Parse the root config (public helper; throws ArkConfigValidationError on invalid config).
+ * Rules use `loadArkContract`, which never throws.
+ */
+declare function loadArkConfig(configPath: string): ArkConfig | null;
+/**
+ * Fingerprint of the Ark contract that applies under `startDir` (default: cwd). ESLint
+ * hashes `settings`, so a recommended config carrying this value invalidates `--cache`
+ * results when ark.config.json or a referenced ArkRules file changes.
+ */
+declare function contractFingerprint(startDir?: string): string | null;
+
+type TsconfigAlias = {
+    /** Pattern text before `*` (whole pattern when it has no `*`). */
+    from: string;
+    /** First target with the trailing `*` removed (legacy shape). */
+    to: string;
+    /** Text after `*` in the pattern ('' for trailing-star patterns). */
+    suffix: string;
+    wildcard: boolean;
+    /** All substitution targets, in declaration order. */
+    targets: string[];
+};
+type TsconfigAliasSet = {
+    baseUrl: string;
+    aliases: TsconfigAlias[];
+};
+/**
+ * Read tsconfig paths/baseUrl for ESLint alias parity (P0-C) from the nearest tsconfig.json
+ * at or above `startDir`.
+ */
+declare function readTsconfigPathAliases(startDir: string): TsconfigAliasSet;
+/** Resolve relative import specifier to an absolute path candidate (TS-oriented). */
+declare function resolveRelativeImport(fromFile: string, specifier: string): string | null;
+/**
+ * Resolve relative or tsconfig path-alias import to an on-disk file.
+ * The tsconfig is the one nearest to `fromFile` (same as the CLI). `projectRoot` is only a
+ * fallback start directory when `fromFile` is empty. Bare packages return null.
+ */
+declare function resolveImportSpecifier(fromFile: string, specifier: string, projectRoot?: string | null): string | null;
+
+type ArkEslintPlugin = {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: Record<string, ArkRule>;
+    configs?: Record<string, unknown>;
+};
+declare const noDomainInfraImports: ArkRule;
+declare const noRawEventPublish: ArkRule;
+declare const requirePublishSource: ArkRule;
+declare const noForbiddenGlobals: ArkRule;
+declare const noDeniedCapabilities: ArkRule;
+declare const noArkRunKernelInDomain: ArkRule;
+declare const noArkRunDirectNew: ArkRule;
+declare const noArkRunTransportBypass: ArkRule;
+declare const noArkOrderKernelInDomain: ArkRule;
+declare const noArkOrderGenericUpdate: ArkRule;
+declare const arkRulesStructureRule: ArkRule;
+declare const architectureAdvisory: ArkRule;
+declare const rules: Record<string, ArkRule>;
+declare const plugin: ArkEslintPlugin;
+declare const configs: Record<string, unknown>;
+
+// @ts-ignore
+export = plugin;
+export { architectureAdvisory, arkRulesStructureRule, configs, contractFingerprint, findConfigPath, globToRegExp, isEdgeDenied, layerForRelativePath, loadArkConfig, noArkOrderGenericUpdate, noArkOrderKernelInDomain, noArkRunDirectNew, noArkRunKernelInDomain, noArkRunTransportBypass, noDeniedCapabilities, noDomainInfraImports, noForbiddenGlobals, noRawEventPublish, patternSpecificity, plugin, readTsconfigPathAliases, requirePublishSource, resolveImportSpecifier, resolveRelativeImport, rules };