@archwall/core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,721 @@
+import { $ as THIRD_PARTY_KINDS, A as primarySourceLocation, B as GraphDelivery, C as ViolationLocation, D as locationsOf, E as fingerprintOf, F as defineClassifier, G as MODULE_ID_SCHEMES, H as GraphMutation, I as Capability, J as ModuleKind, K as ModuleId, L as Edge, M as Classifier, N as ClassifierContext, O as primaryEdge, P as TagPatch, Q as SourceLocation, R as EdgeKind, S as ViolationInput, T as countBySeverity, U as HostInfo, W as IR_VERSION, X as ProjectGraph, Y as ModuleNode, Z as ProjectGraphInit, _ as WellKnownDiagnosticCode, a as defineGraphComputation, at as isFirstParty, b as SeverityCounts, c as GraphQuery, et as WellKnownCapability, f as Diagnostic, g as RuleSkippedDetails, h as EmptyScopeDetails, i as GraphComputation, it as irMajor, j as renderMessage, k as primaryModule, l as ModuleFilter, m as DiagnosticSeverity, n as TransformContext, nt as assertIrCompatible, o as EdgeFilter, ot as isThirdParty, p as DiagnosticCode, q as ModuleIdScheme, r as defineTransform, rt as displayModuleId, st as parseModuleId, t as GraphTransform, tt as WellKnownEdgeKind, u as ModuleSelection, v as FINGERPRINT_SCHEME, w as compareViolations, x as Violation, y as Severity, z as FIRST_PARTY_KINDS } from "./transform-CnUPOO0E.mjs";
+//#region src/analysis/scc.d.ts
+/**
+ * Strongly connected components over static+reexport edges (a dynamic import is a
+ * legal cycle-breaker). Iterative Tarjan — recursion would overflow at 10k+ modules.
+ * Every module appears in exactly one component.
+ */
+declare const stronglyConnectedComponents: GraphComputation<readonly (readonly string[])[]>;
+//#endregion
+//#region src/classifiers/path.d.ts
+interface PathPattern {
+  /**
+   * Glob-lite, relative to the classifier `root` (itself under the config `sourceRoot`),
+   * anchored full-match: `:name` captures one segment as a tag, `*` matches within a
+   * segment, `**` across.
+   */
+  pattern: string;
+  /** Literal tags, merged over the captures. */
+  tags?: Record<string, string>;
+  /**
+   * Constrains captured values. A capture outside its allow-list makes the pattern NOT
+   * match, so the next pattern is tried — this is how unknown top-level folders stay
+   * untagged (and therefore ignored by every rule) instead of inventing layers.
+   */
+  only?: Record<string, readonly string[]>;
+}
+interface PathClassifierOptions {
+  name?: string;
+  /** Directory the patterns are relative to, itself relative to the config `sourceRoot`. Default ".". */
+  root?: string;
+  /** First match wins. */
+  patterns: PathPattern[];
+}
+/**
+ * Declarative path→tag mapping. Every built-in preset is built on this, and it is the
+ * supported way to describe a custom architecture without writing a classify function.
+ */
+declare function pathClassifier(opts: PathClassifierOptions): Classifier;
+//#endregion
+//#region src/contracts/reporter.d.ts
+/**
+ * Where a reporter's output goes.
+ *
+ * `"stdout"` and `"stderr"` are the two every environment has; anything else is a file
+ * path, which only a host with a filesystem can honour. A reporter never decides this —
+ * it writes to the sink it is handed.
+ */
+type OutputDestination = "stdout" | "stderr" | (string & {});
+interface OutputSink {
+  write(text: string): void;
+  /** Flushed and awaited before the run's result is acted on. */
+  close?(): void | Promise<void>;
+}
+/**
+ * Opens destinations. The seam that lets the same built-in reporter write to a terminal,
+ * to stderr, or to `archwall.sarif` without knowing which.
+ *
+ * Per-reporter, so that a machine-readable document and a human summary in the same run
+ * never share a stream.
+ */
+interface ReporterIO {
+  open(destination: OutputDestination): OutputSink;
+}
+interface RunInfo {
+  /**
+   * Unique per analysis. In watch mode one reporter instance may see many runs, and
+   * without a way to tell them apart any per-run state it keeps grows forever. A custom
+   * reporter that accumulates anything should key it on this and drop the previous run's.
+   */
+  runId: string;
+  host: HostInfo;
+  startedAt: number;
+  /** Absolute repository root, so a reporter can relativize before its first output. */
+  repoRoot: string;
+}
+interface AnalysisStats {
+  moduleCount: number;
+  edgeCount: number;
+  durationMs: number;
+}
+/**
+ * What happened to one configured rule instance in this run.
+ *
+ * Without it there is no way to answer "did my rule actually run?" — the question behind
+ * every report of the tool being silently wrong. It is also what lets a reporter emit rule
+ * metadata for rules that produced no violations, which SARIF's `tool.driver.rules` wants.
+ */
+interface RuleRunInfo {
+  /** Instance id — what `overrides` matches and what violations report. */
+  id: string;
+  name: string;
+  description: string;
+  docsUrl?: string;
+  severity: Severity;
+  /**
+   * `ran` — checked, whether or not it found anything.
+   * `skipped` — the host could not provide capabilities it requires.
+   * `failed` — it threw; see the matching `rule-failed` diagnostic.
+   *
+   * Rules dropped for invalid options or invalid configuration never reach the engine and
+   * so are absent here; they appear as diagnostics.
+   */
+  status: "ran" | "skipped" | "failed";
+  /** Violations this instance produced. */
+  violations: number;
+  durationMs: number;
+  /** Present when `status: "skipped"`. */
+  missingCapabilities?: readonly Capability[];
+  /** Present when the rule is deprecated; mirrors the `rule-deprecated` diagnostic. */
+  deprecated?: boolean;
+}
+interface AnalysisResult {
+  /** Deterministically ordered; see `compareViolations`. */
+  violations: readonly Violation[];
+  /** Everything that is not a violation: skipped rules, crashed rules, config problems. */
+  diagnostics: readonly Diagnostic[];
+  stats: AnalysisStats;
+  /** Every rule instance the engine saw, in configuration order. */
+  rules: readonly RuleRunInfo[];
+  host: HostInfo;
+  delivery: GraphDelivery;
+  /**
+   * Absolute repository root. Reporters need it to emit repo-relative paths, and without
+   * it correct SARIF is impossible: `artifactLocation.uri` must be repo-relative or GitHub
+   * code scanning cannot associate a result with a file.
+   */
+  repoRoot: string;
+}
+/**
+ * Two hooks, both batch. There is deliberately no per-violation streaming hook
+ */
+interface Reporter {
+  name: string;
+  /**
+   * Called before the engine runs. The place to reset per-run state, which matters because
+   * one reporter instance can outlive many runs in watch mode.
+   */
+  onRunStart?(info: RunInfo): void | Promise<void>;
+  /** Awaited, so a reporter may write a file or flush a socket. */
+  onRunEnd(result: AnalysisResult): void | Promise<void>;
+}
+declare function defineReporter(reporter: Reporter): Reporter;
+//#endregion
+//#region src/contracts/standard-schema.d.ts
+/**
+ * Vendored Standard Schema v1 interface (standardschema.dev) so zod/valibot/arktype
+ * schemas type-check as rule option schemas without core taking a dependency.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+  };
+}
+type StandardSchemaResult<Output> = {
+  value: Output;
+  issues?: undefined;
+} | {
+  issues: ReadonlyArray<StandardSchemaIssue>;
+};
+interface StandardSchemaIssue {
+  message: string;
+  path?: ReadonlyArray<PropertyKey | {
+    key: PropertyKey;
+  }>;
+}
+//#endregion
+//#region src/contracts/rule.d.ts
+/**
+ * Marks a rule, or one of its options, as on the way out.
+ *
+ * One optional field, and the only thing standing between the project and a choice
+ * between "never rename anything" and "break everyone". The engine turns it into a
+ * `rule-deprecated` diagnostic when a deprecated rule is configured.
+ */
+interface RuleDeprecation {
+  /** Version in which the deprecation was announced. */
+  since: string;
+  /** Instance id or rule name to migrate to, when there is a direct replacement. */
+  replacedBy?: string;
+  /** Why, and what to do instead, when `replacedBy` alone does not say it. */
+  reason?: string;
+  /** Option names that are deprecated, when the rule itself is not. */
+  options?: Record<string, string>;
+}
+interface RuleMeta<Options> {
+  name: string;
+  description: string;
+  docsUrl?: string;
+  optionsSchema?: StandardSchemaV1<unknown, Options>;
+  defaultSeverity: Severity;
+  requiredCapabilities?: Capability[];
+  /**
+   * `messageId` → template, with `{placeholder}` interpolation from the reported `data`.
+   *
+   * Rules report an id and a data bag rather than a finished sentence, so the wording stays
+   * a property of the rule's *metadata*: retargetable per instance via
+   * `ConfiguredRule.message`, translatable, and machine-groupable.
+   */
+  messages?: Record<string, string>;
+  /** Part of the curated set a "recommended" preset would enable. */
+  recommended?: boolean;
+  deprecated?: RuleDeprecation;
+}
+interface RuleContext<Options> {
+  options: Options;
+  graph: GraphQuery;
+  /**
+   * Absolute source root. The base for any path *pattern* a rule matches against, so that
+   * rule options read the same way as classifier patterns and `include`/`exclude`.
+   */
+  sourceRoot: string;
+  /**
+   * Absolute repository root. For paths a rule puts in front of a human or another tool;
+   * reporters relativize against this.
+   */
+  repoRoot: string;
+  /**
+   * A file's path relative to {@link sourceRoot}, forward-slashed, or null when it lies
+   * outside. Every rule that matches paths needs exactly this, and hand-rolling it is how
+   * six copies with three different edge-case behaviours came to exist.
+   */
+  relative(file: string): string | null;
+  /**
+   * A module id as a human should read it — `src/domain/rules.ts`, `react`, `node:fs`.
+   *
+   * Use it for anything that goes into a message's `data`. A canonical {@link ModuleId} is
+   * scheme-prefixed, and a rule that interpolates one raw puts `file:src/a.ts` in front of a
+   * user.
+   */
+  display(id: ModuleId): string;
+  /**
+   * Shared memoized graph computations, one evaluation per run.
+   *
+   * Scoped like `graph`: a computation requested by a scoped rule is evaluated over that rule's
+   * slice.
+   */
+  compute<T>(computation: GraphComputation<T>): T;
+  report(violation: ViolationInput): void;
+}
+/**
+ * What a rule wants to look at, declared rather than fetched.
+ *
+ * The engine owns the traversal, so one slice of the graph is evaluated once for every rule
+ * that wants it, and the engine knows which rules a given edge can affect — the
+ * prerequisite for incremental validation.
+ *
+ * `check` remains for rules that genuinely need the whole graph at once (cycle detection,
+ * reachability). It is the exception, not the interface.
+ */
+interface RuleVisitors<Options> {
+  edges?: {
+    /**
+     * Narrows the edges `visit` receives. A function of the rule's options, because the
+     * interesting filters depend on them (`crossing: options.tagKey`).
+     */
+    filter?: (options: Options) => EdgeFilter | undefined;
+    visit(edge: Edge, ctx: RuleContext<Options>): void;
+  };
+  modules?: {
+    filter?: (options: Options) => ModuleFilter | undefined;
+    visit(module: ModuleNode, ctx: RuleContext<Options>): void;
+  };
+}
+interface Rule<Options = unknown> {
+  meta: RuleMeta<Options>;
+  /** Declared interest; the engine drives the traversal. Preferred. */
+  visits?: RuleVisitors<Options>;
+  /** Whole-graph escape hatch, for rules that cannot be expressed as a traversal. */
+  check?(ctx: RuleContext<Options>): void | Promise<void>;
+}
+/**
+ * Instance settings, deliberately a SEPARATE bag from the rule's options, so that no
+ * option name is reserved across every rule that will ever exist.
+ */
+interface RuleSettings {
+  id?: string;
+  severity?: Severity | "off";
+  scope?: RuleScope;
+  /**
+   * Retargets this instance's wording: one template when the rule has a single message, or
+   * `messageId` → template.
+   */
+  message?: string | Record<string, string>;
+}
+/**
+ * Restricts one rule instance to part of the graph.
+ *
+ * This is what makes a monorepo expressible: "FSD under `apps/web`, layered under
+ * `services/api`" is two instances of two rules with two scopes, in ONE config and ONE
+ * pass. Applied by the ENGINE, by narrowing the `GraphQuery` a rule receives, so every
+ * rule that will ever be written inherits scoping for free and none of them has to know it
+ * exists.
+ */
+interface RuleScope {
+  /**
+   * Glob-lite paths relative to `sourceRoot`, matched against module files. Default: the
+   * whole project.
+   */
+  include?: string[];
+  /** Glob-lite paths to remove from `include`. */
+  exclude?: string[];
+  /** Only modules carrying ALL of these tags. */
+  tag?: Record<string, string>;
+}
+/** A rule that is also a function returning a configured instance of itself. */
+interface CallableRule<Options = unknown> extends Rule<Options> {
+  (options?: Partial<Options>, settings?: RuleSettings): ConfiguredRule<Options>;
+}
+declare function defineRule<O>(rule: Rule<O>): CallableRule<O>;
+/**
+ * A configured rule instance whose option type is not known at the use site — what a
+ * `Preset`, a `UserConfig`, and the engine all hold.
+ *
+ * `any` rather than `unknown` deliberately: `RuleVisitors` puts `Options` in contravariant
+ * position (`filter(options)`, `visit(item, ctx)`), which makes `ConfiguredRule` invariant
+ * in `Options`, so `ConfiguredRule<unknown>` would reject every concrete rule there is.
+ */
+type AnyConfiguredRule = ConfiguredRule<any>;
+interface ConfiguredRule<O = unknown> {
+  rule: Rule<O>;
+  /**
+   * Merge key and `overrides` key. Inside a preset it defaults to
+   * `<preset>/<rule.meta.name>`; elsewhere to `rule.meta.name`. Set it explicitly to carry
+   * two instances of the same rule in one preset.
+   */
+  id?: string;
+  options?: Partial<O>;
+  severity?: Severity | "off";
+  /** Restricts this instance to part of the graph; applied by the engine. */
+  scope?: RuleScope;
+  /** Per-instance message templates; see {@link RuleSettings.message}. */
+  message?: string | Record<string, string>;
+}
+declare function configureRule<O>(rule: Rule<O>, options?: Partial<O>, settings?: RuleSettings): ConfiguredRule<O>;
+//#endregion
+//#region src/contracts/preset.d.ts
+/**
+ * Everything a third party can ship as one installable unit.
+ *
+ * There is deliberately no separate `Plugin` type above this one. A second, near-identical
+ * bundle would mean everyone has to learn which of the two they need and every downstream
+ * API has to accept both; widening the one bundle that already exists costs a few optional
+ * fields and no new vocabulary.
+ *
+ * The optional fields are declared up front on purpose: `Preset` is promised as stable, and
+ * adding a field to a stable type is a breaking change for anyone who wrote
+ * `satisfies Preset`.
+ */
+/**
+ * Descriptive facts about a preset. Nothing in core reads these yet — they exist now because
+ * `Preset` is promised as stable, so this is the last moment at which adding them is free.
+ *
+ * The index signature is the load-bearing part: with it, every future named field is additive
+ * and a third party can carry its own facts without waiting for core. Without it, this type
+ * would have exactly the problem it exists to solve.
+ */
+interface PresetMeta {
+  /** The preset package's version, for reporters and bug reports. */
+  version?: string;
+  description?: string;
+  docsUrl?: string;
+  [key: string]: unknown;
+}
+interface Preset {
+  name: string;
+  classifiers: Classifier[];
+  rules: AnyConfiguredRule[];
+  /** See {@link PresetMeta}. Purely descriptive; it never affects analysis. */
+  meta?: PresetMeta;
+  /**
+   * Passes that enrich the graph before classification — the slot a TypeScript type-edge
+   * enricher, or any other "add facts the bundler didn't give us" pass, lives in.
+   */
+  transforms?: GraphTransform[];
+  /**
+   * Reporters the preset contributes. Appended to whatever the user configured rather
+   * than replacing it: a preset that ships an uploader should not silently remove the
+   * console output the user is reading.
+   */
+  reporters?: Reporter[];
+}
+declare function definePreset<A extends unknown[]>(fn: (...args: A) => Preset): (...args: A) => Preset;
+//#endregion
+//#region src/reporters/resolve.d.ts
+type BuiltinReporterName = "console" | "json" | "sarif";
+declare const BUILTIN_REPORTER_NAMES: readonly BuiltinReporterName[];
+declare function isBuiltinReporterName(name: string): name is BuiltinReporterName;
+/**
+ * A reporter plus where its output goes.
+ *
+ * The object form exists so that `sarif` can write `archwall.sarif` while `console` keeps
+ * the terminal, in one run. Without it every reporter shares one stream and machine-readable
+ * output is contaminated by human-readable output.
+ */
+interface ReporterOutputSpec {
+  reporter: BuiltinReporterName | Reporter;
+  /** Default `"stdout"`. Also accepts `"stderr"` or a file path. */
+  output?: OutputDestination;
+}
+/**
+ * `string` is accepted so a config file can name a third-party reporter
+ * (`"archwall-reporter-teamcity"`). Those are resolved to objects before reaching the
+ * engine; a string that survives to here is one nothing could load.
+ */
+type ReporterSpec = BuiltinReporterName | Reporter | ReporterOutputSpec | (string & {});
+interface ResolvedReporters {
+  reporters: readonly Reporter[];
+  /** Closes every sink this opened. Awaited after `onRunEnd`, before acting on the result. */
+  close(): Promise<void>;
+}
+declare function resolveReporters(specs: readonly ReporterSpec[], io?: ReporterIO): ResolvedReporters;
+//#endregion
+//#region src/config.d.ts
+type FailOn = "error" | "warn" | "never";
+/**
+ * Which diagnostics are severe enough to fail the run, independently of violations.
+ *
+ * `ruleFailed` and `invalidConfig` default to true and should stay that way: a rule that
+ * throws, and a rule dropped because its configuration was invalid, both produce no results
+ * — so a run in which either happened is a run that did not check what you asked it to. An
+ * enforcement tool that passes green when a rule crashes is not an enforcement tool.
+ */
+interface FailOnDiagnostics {
+  /** A rule threw. Default true. */
+  ruleFailed?: boolean;
+  /** A rule was skipped for missing host capabilities. Default false. */
+  ruleSkipped?: boolean;
+  /** Classification tagged nothing, or the boundary matched nothing. Default false. */
+  emptyAnalysis?: boolean;
+  /**
+   * A rule's `scope` resolved to zero modules. Default false.
+   *
+   * Its own switch rather than part of `emptyAnalysis`: "the run looked at nothing" and "this
+   * one rule looked at nothing" are different failures, and a monorepo where some packages
+   * legitimately have no modules yet wants to tolerate the second while still gating the first.
+   */
+  emptyScope?: boolean;
+  /** A rule's options failed its schema, so the rule did not run. Default true. */
+  invalidOptions?: boolean;
+  /** The configuration itself is wrong and something was dropped. Default true. */
+  invalidConfig?: boolean;
+  /** A configured rule is deprecated. Default false. */
+  deprecated?: boolean;
+}
+interface ResolvedFailOnDiagnostics {
+  ruleFailed: boolean;
+  ruleSkipped: boolean;
+  emptyAnalysis: boolean;
+  emptyScope: boolean;
+  invalidOptions: boolean;
+  invalidConfig: boolean;
+  deprecated: boolean;
+}
+/**
+ * Which diagnostic codes each `failOnDiagnostics` switch governs, and whether it is on by
+ * default. The single source of truth for both.
+ *
+ * One table because there used to be three: the code list lived in `@archwall/integration-kit`,
+ * the defaults lived in `resolveConfig` below, and a second copy of the defaults lived beside
+ * the code list. Nothing linked them, so adding a gate meant remembering all three, and
+ * forgetting the third produced a switch that resolved correctly and then gated nothing.
+ *
+ * The `satisfies` is what keeps it honest: a key added to {@link ResolvedFailOnDiagnostics}
+ * and not here is a compile error, and vice versa.
+ */
+declare const DIAGNOSTIC_GATES: {
+  readonly ruleFailed: {
+    readonly codes: readonly ["rule-failed"];
+    readonly default: true;
+  };
+  readonly ruleSkipped: {
+    readonly codes: readonly ["rule-skipped"];
+    readonly default: false;
+  };
+  readonly emptyAnalysis: {
+    readonly codes: readonly ["no-modules-classified", "empty-project"];
+    readonly default: false;
+  };
+  readonly emptyScope: {
+    readonly codes: readonly ["empty-scope"];
+    readonly default: false;
+  };
+  readonly invalidOptions: {
+    readonly codes: readonly ["invalid-rule-options"];
+    readonly default: true;
+  };
+  readonly invalidConfig: {
+    readonly codes: readonly ["invalid-config"];
+    readonly default: true;
+  };
+  readonly deprecated: {
+    readonly codes: readonly ["rule-deprecated"];
+    readonly default: false;
+  };
+};
+/**
+ * Applies {@link DIAGNOSTIC_GATES}' defaults to whatever the user left unset.
+ *
+ * Spelled out key by key rather than mapped over `GATE_KEYS`, so that adding a gate is a
+ * compile error here until it is handled. The values still come from the one table; only the
+ * exhaustiveness is restated, and restating it is the thing being bought.
+ */
+declare function resolveFailOnDiagnostics(user: FailOnDiagnostics | undefined): ResolvedFailOnDiagnostics;
+/** The diagnostic codes that should fail a run, given the resolved gates. */
+declare function failingDiagnosticCodes(gates: ResolvedFailOnDiagnostics): Set<DiagnosticCode>;
+/**
+ * Retune one rule instance. The shorthand form sets severity only; the object form can also
+ * patch options, scope, and wording.
+ *
+ * Options merge by ONE policy, the same one used everywhere: **top-level keys replace, and
+ * arrays are replaced wholesale, never concatenated.**
+ */
+type RuleOverride = Severity | "off" | {
+  severity?: Severity | "off";
+  options?: Record<string, unknown>;
+  scope?: RuleScope;
+  message?: string | Record<string, string>;
+};
+/**
+ * A preset, or the name of a package exporting one.
+ *
+ * The string form is what makes a plugin ecosystem possible: without it a preset can only
+ * be `import`ed, which forecloses JSON/YAML configuration and any `--preset` flag forever.
+ * Strings are resolved by the config loader (`@archwall/integration-kit`), which is the
+ * layer that has a module resolver; one that reaches {@link resolveConfig} unresolved is
+ * reported as a configuration error rather than silently ignored.
+ *
+ * `["@acme/preset", { … }]` calls the package's default export with those options.
+ */
+type PresetSpec = Preset | string | readonly [string, Record<string, unknown>?];
+/** A configured rule, or the name of a package/built-in exporting one. See {@link PresetSpec}. */
+type RuleSpec = AnyConfiguredRule | string | readonly [string, Record<string, unknown>?, RuleSettings?];
+interface UserConfig {
+  /**
+   * Configurations to inherit from, nearest-last: a later entry wins over an earlier one,
+   * and this config wins over all of them.
+   *
+   * Arrays (`presets`, `rules`, `classifiers`, `transforms`, `reporters`, `exclude`)
+   * CONCATENATE base-first, because rules already merge by instance id downstream and
+   * `overrides` already exists for retuning. Scalars replace. `overrides` merges key-wise.
+   *
+   * This is the only way to ship an organisation-wide configuration: a `Preset` cannot set
+   * `failOn`, `include`, `exclude`, `repoRoot`, or `reporters`, so without `extends` a
+   * shared config is a preset plus a README telling every repository to copy twenty lines.
+   */
+  extends?: string | string[];
+  /**
+   * Where the *repository* starts, relative to the config file / cwd. Default ".".
+   *
+   * The base for everything that leaves the process — reporter output, SARIF
+   * `artifactLocation.uri`, violation fingerprints — so it must be the path a checkout is
+   * rooted at, not the path your sources happen to live under.
+   */
+  repoRoot?: string;
+  /**
+   * Where the *sources* start, relative to {@link repoRoot}. Default ".".
+   *
+   * The base for `include`/`exclude` matching and for classifier patterns — the tree whose
+   * shape your architecture is described in. This is the one that is usually `"src"`.
+   */
+  sourceRoot?: string;
+  include?: string[];
+  /**
+   * Patterns ADDED to the defaults (`node_modules`, `*.test.*`, `*.spec.*`), not a
+   * replacement for them. Use {@link excludeDefaults} to opt out deliberately.
+   */
+  exclude?: string[];
+  /** Set false to drop the built-in `exclude` defaults entirely. */
+  excludeDefaults?: boolean;
+  presets?: PresetSpec[];
+  /** Appended after preset classifiers. */
+  classifiers?: Classifier[];
+  /** Appended after preset transforms; run between the project boundary and classification. */
+  transforms?: GraphTransform[];
+  /** Merged after preset rules (last-writer-wins, keyed by rule instance id). */
+  rules?: RuleSpec[];
+  /**
+   * Retunes rule instances; ALWAYS wins over presets and rules. Keys are an exact instance
+   * id ("fsd/public-api"), a bare rule name (every instance of it), or a glob ("fsd/*").
+   * A key that matches no rule is an error, not a silent no-op.
+   */
+  overrides?: Record<string, RuleOverride>;
+  /**
+   * Built-ins by name, customs by object, third-party by package name, and
+   * `{ reporter, output }` to send one somewhere other than stdout. Default ["console"].
+   */
+  reporters?: ReporterSpec[];
+  /** Which VIOLATION severity gates the run. `info` findings never fail it. */
+  failOn?: FailOn;
+  /** Which DIAGNOSTICS gate the run, regardless of `failOn`. */
+  failOnDiagnostics?: FailOnDiagnostics;
+}
+declare function defineConfig(config: UserConfig): UserConfig;
+interface ResolvedRule {
+  rule: Rule<any>;
+  /** Instance id; what violations report and what `overrides` keys match. */
+  id: string;
+  options: unknown;
+  severity: Severity;
+  /** Narrows the graph this instance sees; applied by the engine, never by the rule. */
+  scope?: RuleScope;
+  /** Per-instance message templates. */
+  message?: string | Record<string, string>;
+}
+interface ResolvedConfig {
+  /** Absolute. Base for reported paths and fingerprints. */
+  repoRoot: string;
+  /** Absolute, at or below {@link repoRoot}. Base for the boundary and classifiers. */
+  sourceRoot: string;
+  include: string[];
+  exclude: string[];
+  classifiers: readonly Classifier[];
+  transforms: readonly GraphTransform[];
+  rules: readonly ResolvedRule[];
+  /** Reporter instantiation is deferred to the run edge (resolveReporters). */
+  reporterSpecs: readonly ReporterSpec[];
+  failOn: FailOn;
+  failOnDiagnostics: ResolvedFailOnDiagnostics;
+  /**
+   * Everything wrong with the configuration itself, found before any graph work.
+   *
+   * Reported rather than thrown: a throw inside a bundler's `buildEnd` produces a stack
+   * trace and destroys every other finding in the run. One mistyped `overrides` key costs
+   * you that key, not the analysis — and `failOnDiagnostics.invalidConfig` still fails the
+   * run.
+   */
+  diagnostics: readonly Diagnostic[];
+}
+declare function resolveConfig(user: UserConfig, opts?: {
+  cwd?: string;
+}): ResolvedConfig;
+//#endregion
+//#region src/engine/analyze.d.ts
+/**
+ * The engine: prepare the graph (boundary → transforms → classify), then check it.
+ *
+ * Pure — no I/O, no reporter calls; reporters are driven by the run edge (integration-kit).
+ */
+declare function analyze(graph: ProjectGraph, config: ResolvedConfig): Promise<AnalysisResult>;
+//#endregion
+//#region src/errors.d.ts
+declare class ArchWallError extends Error {
+  constructor(message: string);
+}
+declare class IrVersionMismatchError extends ArchWallError {
+  readonly graphVersion: string;
+  readonly coreVersion: string;
+  constructor(graphVersion: string, coreVersion: string);
+}
+//#endregion
+//#region src/match.d.ts
+/**
+ * Anchored full-match test.
+ *
+ * `dot: true` so a pattern matches dotfiles without every caller remembering to say so —
+ * a rule that silently skips `.storybook/` is the kind of quiet gap this tool exists to
+ * prevent.
+ */
+declare function matchesPattern(value: string, pattern: string): boolean;
+/**
+ * Anchored full-match returning the `:name` captures, or null when the pattern does not
+ * match. A pattern with no captures yields an empty object on match — callers must check
+ * for null rather than for emptiness.
+ */
+declare function matchCaptures(value: string, pattern: string): Record<string, string> | null;
+//#endregion
+//#region src/reporters/console.d.ts
+/**
+ * Console-only IO: the portable default.
+ *
+ * Core stays runnable wherever a graph can be built — browser playground, worker, edge
+ * runtime — so it cannot open files. A host with a filesystem supplies an IO that can
+ * (`@archwall/integration-kit` exports `nodeIO`); asking this one for a file is an error
+ * rather than a silent fallback to stdout, because a run that was told to write
+ * `archwall.sarif` and printed to the terminal instead has failed at its actual job.
+ */
+declare const defaultIO: ReporterIO;
+/**
+ * Shared violation block format — also used by adapters when mapping violations into host
+ * diagnostics (error locality: anchored on the importer edge, resolution shown as
+ * explanation, never as the location).
+ *
+ * `repoRoot` makes every path repository-relative. Absolute paths are the right module
+ * identity inside a run and the wrong thing in every output.
+ */
+declare function formatViolation(v: Violation, repoRoot?: string): string;
+/**
+ * Stateless: one pass over the finished result, in `onRunEnd`.
+ *
+ * There is no `onRunStart` and no per-run state to reset, which is what makes it safe for
+ * the run object to be memoized across watch rebuilds in the bundler adapters — a reporter
+ * that accumulated anything would grow for the life of the process.
+ */
+declare function consoleReporter(sink: OutputSink): Reporter;
+//#endregion
+//#region src/reporters/json.d.ts
+declare function jsonReporter(sink: OutputSink): Reporter;
+//#endregion
+//#region src/reporters/sarif.d.ts
+declare function sarifReporter(sink: OutputSink): Reporter;
+//#endregion
+//#region src/transforms/drop-self-edges.d.ts
+/**
+ * Removes edges from a module to itself.
+ *
+ * This is a *semantic policy*, and it belongs in shared code a host opts into rather than
+ * inside one adapter: HMR instrumentation adds self-edges (React Fast Refresh makes every
+ * transformed component module import itself), and that reasoning is not Vite-specific —
+ * the moment another bundler's HMR does the same thing, an adapter-local fix has to be
+ * written a second time, and the two can then disagree.
+ *
+ * Deliberately NOT on by default: a genuine self-import is a real finding, and build mode
+ * sees the real graph. A host applies this only where it knows its own instrumentation
+ * created the edges.
+ */
+declare function dropSelfEdges(): GraphTransform;
+//#endregion
+export { type AnalysisResult, type AnalysisStats, ArchWallError, BUILTIN_REPORTER_NAMES, type BuiltinReporterName, type CallableRule, type Capability, type Classifier, type ClassifierContext, type ConfiguredRule, DIAGNOSTIC_GATES, type Diagnostic, type DiagnosticCode, type DiagnosticSeverity, type Edge, type EdgeFilter, type EdgeKind, type EmptyScopeDetails, FINGERPRINT_SCHEME, FIRST_PARTY_KINDS, type FailOn, type FailOnDiagnostics, type GraphComputation, type GraphDelivery, type GraphMutation, GraphQuery, type GraphTransform, type HostInfo, IR_VERSION, IrVersionMismatchError, MODULE_ID_SCHEMES, type ModuleFilter, type ModuleId, type ModuleIdScheme, type ModuleKind, type ModuleNode, type ModuleSelection, type OutputDestination, type OutputSink, type PathClassifierOptions, type PathPattern, type Preset, type PresetMeta, type PresetSpec, ProjectGraph, type ProjectGraphInit, type Reporter, type ReporterIO, type ReporterOutputSpec, type ReporterSpec, type ResolvedConfig, type ResolvedFailOnDiagnostics, type ResolvedReporters, type ResolvedRule, type Rule, type RuleContext, type RuleDeprecation, type RuleMeta, type RuleOverride, type RuleRunInfo, type RuleScope, type RuleSettings, type RuleSkippedDetails, type RuleSpec, type RuleVisitors, type RunInfo, type Severity, type SeverityCounts, type SourceLocation, type StandardSchemaIssue, type StandardSchemaResult, type StandardSchemaV1, THIRD_PARTY_KINDS, type TagPatch, type TransformContext, type UserConfig, type Violation, type ViolationInput, type ViolationLocation, type WellKnownCapability, type WellKnownDiagnosticCode, type WellKnownEdgeKind, analyze, assertIrCompatible, compareViolations, configureRule, consoleReporter, countBySeverity, defaultIO, defineClassifier, defineConfig, defineGraphComputation, definePreset, defineReporter, defineRule, defineTransform, displayModuleId, dropSelfEdges, failingDiagnosticCodes, fingerprintOf, formatViolation, irMajor, isBuiltinReporterName, isFirstParty, isThirdParty, jsonReporter, locationsOf, matchCaptures, matchesPattern, parseModuleId, pathClassifier, primaryEdge, primaryModule, primarySourceLocation, renderMessage, resolveConfig, resolveFailOnDiagnostics, resolveReporters, sarifReporter, stronglyConnectedComponents };
+//# sourceMappingURL=index.d.mts.map