@nielspeter/eess 0.1.0

package/dist/terminal-builder.js

@@ -0,0 +1,134 @@
+import { isSilent } from './silent-exclusion.js';
+import { executeCheck, executeWarn, applyFilters } from './execute-rule.js';
+/**
+ * Abstract base class for builders that share the terminal method pattern
+ * (because, rule, excluding, check, warn, severity) but have different
+ * element collection and evaluation models.
+ *
+ * Used by SliceRuleBuilder, SchemaRuleBuilder, ResolverRuleBuilder,
+ * PairFinalBuilder, and SmellBuilder — all of which implement the same
+ * terminal methods but differ in how they collect and evaluate elements.
+ *
+ * RuleBuilder<T> does NOT extend this because it predates it and has
+ * additional concerns (predicate/condition pipeline, fork semantics).
+ */
+export class TerminalBuilder {
+    _reason;
+    _metadata;
+    _exclusions = [];
+    _silentIndices = new Set();
+    /**
+     * Attach a human-readable rationale to the rule.
+     * Included in violation messages when `.check()` throws.
+     */
+    because(reason) {
+        this._reason = reason;
+        return this;
+    }
+    /**
+     * Attach rich metadata to the rule.
+     * Provides educational context in violation output: why, how to fix, docs link.
+     *
+     * If `metadata.because` is set, it also sets the reason (same as `.because()`).
+     */
+    rule(metadata) {
+        this._metadata = metadata;
+        if (metadata.because) {
+            this._reason = metadata.because;
+        }
+        return this;
+    }
+    /**
+     * Exclude specific elements from violation reporting.
+     *
+     * Matched violations are silently suppressed. Use for permanent,
+     * intentional exceptions — not for temporary violations (use baseline for those).
+     *
+     * Matches against the violation's `element` field.
+     * Supports exact strings and regex patterns.
+     *
+     * Emits a warning if an exclusion matches zero violations (stale exclusion).
+     */
+    excluding(...patterns) {
+        for (const p of patterns) {
+            if (isSilent(p)) {
+                this._exclusions.push(p.pattern);
+                this._silentIndices.add(this._exclusions.length - 1);
+            }
+            else {
+                this._exclusions.push(p);
+            }
+        }
+        return this;
+    }
+    /**
+     * Return a structured description of this rule without executing it.
+     * Used by the `explain` CLI subcommand.
+     */
+    describeRule() {
+        return {
+            rule: this._metadata?.id ?? 'unnamed',
+            id: this._metadata?.id,
+            because: this._reason,
+            suggestion: this._metadata?.suggestion,
+            docs: this._metadata?.docs,
+        };
+    }
+    /**
+     * Execute the rule and return violations after exclusion filtering.
+     * Does not throw — use for programmatic access (presets, aggregation).
+     */
+    violations() {
+        const raw = this.collectViolations();
+        return applyFilters(raw, {
+            reason: this._reason,
+            metadata: this._metadata,
+            exclusions: this._exclusions,
+            silentIndices: this._silentIndices,
+        });
+    }
+    /**
+     * Execute the rule and throw `ArchRuleError` if any violations are found.
+     * This is the primary terminal method — use in test assertions.
+     *
+     * @param options - Optional baseline, diff filtering, and output format
+     */
+    check(options) {
+        const violations = this.collectViolations();
+        executeCheck(violations, {
+            reason: this._reason,
+            metadata: this._metadata,
+            exclusions: this._exclusions,
+            silentIndices: this._silentIndices,
+        }, options);
+    }
+    /**
+     * Execute the rule and log violations to stderr. Does not throw.
+     * Use for rules that should warn but not fail CI.
+     *
+     * @param options - Optional baseline, diff filtering, and output format
+     */
+    warn(options) {
+        const violations = this.collectViolations();
+        executeWarn(violations, {
+            reason: this._reason,
+            metadata: this._metadata,
+            exclusions: this._exclusions,
+            silentIndices: this._silentIndices,
+        }, options);
+    }
+    /**
+     * Execute the rule with the given severity.
+     * `.severity('error')` is equivalent to `.check()`.
+     * `.severity('warn')` is equivalent to `.warn()`.
+     */
+    severity(level) {
+        if (level === 'error') {
+            this.check();
+        }
+        else {
+            this.warn();
+        }
+    }
+}
+//# sourceMappingURL=terminal-builder.js.map

package/dist/terminal-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-builder.js","sourceRoot":"","sources":["../src/terminal-builder.ts"],"names":[],"mappings":"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"}

package/dist/violation.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A single architecture rule violation.
+ *
+ * Represents one element that failed to satisfy a condition. This is the
+ * kernel's central data type — dialect-independent. Each dialect provides its
+ * own adapter that builds an `ArchViolation` from that dialect's element type
+ * (e.g. the TS dialect builds one from a ts-morph `Node`).
+ */
+/**
+ * A deterministic, unique text edit that repairs a violation (plan 0066). Emitted
+ * by a condition ONLY when the fix is provably unambiguous (e.g. a broken link
+ * whose target resolves to exactly one file); ambiguous or judgment cases carry
+ * no fix and are reported instead. `applyFixes` writes these.
+ */
+export interface ArchFix {
+    /** Absolute path of the file to edit. */
+    file: string;
+    /** 0-based character offset of the start of the span to replace. */
+    start: number;
+    /** 0-based character offset of the end of the span (exclusive). */
+    end: number;
+    /** Replacement text for `[start, end)`. */
+    replacement: string;
+    /** One-line human description, e.g. 'rewrite link → work/plans/completed/0009.md'. */
+    describe: string;
+}
+export interface ArchViolation {
+    /** Human-readable rule description (from the fluent chain) */
+    rule: string;
+    /** Unique rule identifier from .rule({ id }) */
+    ruleId?: string;
+    /** Element identifier, e.g. "OrderService.getTotal()" or "parseConfig" */
+    element: string;
+    /** Absolute file path where the violation occurs */
+    file: string;
+    /** Line number where the violating element starts */
+    line: number;
+    /** Human-readable description of what went wrong */
+    message: string;
+    /** Optional rationale provided via .because() */
+    because?: string;
+    /** Source code snippet around the violation line */
+    codeFrame?: string;
+    /** Actionable suggestion for fixing the violation (e.g. "Replace parseInt() with this.extractCount()") */
+    suggestion?: string;
+    /** Link to documentation — ADR, wiki, style guide */
+    docs?: string;
+    /** A deterministic, unique text edit that repairs this violation (plan 0066). */
+    fix?: ArchFix;
+}
+//# sourceMappingURL=violation.d.ts.map

package/dist/violation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"violation.d.ts","sourceRoot":"","sources":["../src/violation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;IACb,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAA;IACX,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAA;IACnB,sFAAsF;IACtF,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAA;IACf,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAA;IACZ,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAA;IACf,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0GAA0G;IAC1G,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iFAAiF;IACjF,GAAG,CAAC,EAAE,OAAO,CAAA;CACd"}

package/dist/violation.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=violation.js.map

package/dist/violation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"violation.js","sourceRoot":"","sources":["../src/violation.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@nielspeter/eess",
+  "version": "0.1.0",
+  "description": "eess kernel — the dialect-independent rule engine (RuleBuilder, Predicate, Condition, baseline, formatters). Specifications you can run.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nielspeter/eess.git",
+    "directory": "packages/core"
+  },
+  "author": "Niels Peter",
+  "license": "MIT",
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "eess",
+    "architecture-testing",
+    "rule-engine",
+    "specification"
+  ]
+}