@nielspeter/eess-ts 0.1.0

package/dist/helpers/matchers.js

@@ -0,0 +1,470 @@
+import { Node, SyntaxKind } from 'ts-morph';
+/**
+ * Normalize expression text for matching.
+ * Replaces optional chaining `?.` with `.` so users don't need to
+ * account for both forms.
+ *
+ * PoC finding: `this?.normalizeCount` getText() includes the `?`.
+ */
+function normalizeText(text) {
+    return text.replace(/\?\./g, '.');
+}
+/**
+ * Match a CallExpression by function/method name.
+ *
+ * Matches against `CallExpression.getExpression().getText()` after
+ * normalizing optional chaining.
+ *
+ * @param nameOrRegex - Exact name (e.g. 'parseInt', 'this.normalizeCount')
+ *                      or regex for flexible matching.
+ *
+ * @example
+ * call('parseInt')                    // matches parseInt(x)
+ * call('this.normalizeCount')         // matches this.normalizeCount(x) AND this?.normalizeCount(x)
+ * call(/^console\./)                  // matches console.log, console.warn, etc.
+ */
+export function call(nameOrRegex) {
+    if (typeof nameOrRegex === 'string') {
+        return {
+            description: `call to '${nameOrRegex}'`,
+            syntaxKinds: [SyntaxKind.CallExpression],
+            matches(node) {
+                if (!Node.isCallExpression(node))
+                    return false;
+                const text = normalizeText(node.getExpression().getText());
+                return text === nameOrRegex;
+            },
+        };
+    }
+    return {
+        description: `call matching ${String(nameOrRegex)}`,
+        syntaxKinds: [SyntaxKind.CallExpression],
+        matches(node) {
+            if (!Node.isCallExpression(node))
+                return false;
+            const text = normalizeText(node.getExpression().getText());
+            return nameOrRegex.test(text);
+        },
+    };
+}
+/**
+ * Match a PropertyAccessExpression by the dotted chain.
+ *
+ * Matches against `PropertyAccessExpression.getText()` after normalizing
+ * optional chaining. Useful for detecting direct property access patterns
+ * like `process.env`, `this.db`, `window.location`.
+ *
+ * @param chain - Exact dotted chain (e.g. 'process.env') or regex.
+ *
+ * @example
+ * access('process.env')               // matches process.env.FOO (the inner access)
+ * access(/^this\.db/)                 // matches this.db, this.db.query, etc.
+ */
+export function access(chain) {
+    if (typeof chain === 'string') {
+        return {
+            description: `access to '${chain}'`,
+            syntaxKinds: [SyntaxKind.PropertyAccessExpression],
+            matches(node) {
+                if (!Node.isPropertyAccessExpression(node))
+                    return false;
+                const text = normalizeText(node.getText());
+                return text === chain;
+            },
+        };
+    }
+    return {
+        description: `access matching ${String(chain)}`,
+        syntaxKinds: [SyntaxKind.PropertyAccessExpression],
+        matches(node) {
+            if (!Node.isPropertyAccessExpression(node))
+                return false;
+            const text = normalizeText(node.getText());
+            return chain.test(text);
+        },
+    };
+}
+/**
+ * Match a NewExpression by constructor name.
+ *
+ * Matches against `NewExpression.getExpression().getText()`.
+ * The PoC confirmed this correctly distinguishes 'Error' from 'DomainError'.
+ *
+ * @param nameOrRegex - Exact constructor name or regex.
+ *
+ * @example
+ * newExpr('Error')                    // matches new Error(...) but NOT new DomainError(...)
+ * newExpr('DomainError')              // matches new DomainError(...)
+ * newExpr(/Error$/)                   // matches new Error, new DomainError, new TypeError, etc.
+ */
+export function newExpr(nameOrRegex) {
+    if (typeof nameOrRegex === 'string') {
+        return {
+            description: `new '${nameOrRegex}'`,
+            syntaxKinds: [SyntaxKind.NewExpression],
+            matches(node) {
+                if (!Node.isNewExpression(node))
+                    return false;
+                const text = node.getExpression().getText();
+                return text === nameOrRegex;
+            },
+        };
+    }
+    return {
+        description: `new matching ${String(nameOrRegex)}`,
+        syntaxKinds: [SyntaxKind.NewExpression],
+        matches(node) {
+            if (!Node.isNewExpression(node))
+                return false;
+            const text = node.getExpression().getText();
+            return nameOrRegex.test(text);
+        },
+    };
+}
+/**
+ * Escape hatch: match any node whose getText() contains or matches the given pattern.
+ *
+ * This is intentionally broad and should be used sparingly. It walks ALL
+ * descendant nodes and checks getText() against the pattern. A runtime
+ * console.warn is emitted the first time expression() is used, encouraging
+ * users to prefer call/access/newExpr where possible.
+ *
+ * @param textOrRegex - Substring to search for (string) or regex pattern.
+ *
+ * @example
+ * expression('eval')                  // matches any node containing 'eval'
+ * expression(/document\.write/)       // matches document.write calls
+ */
+export function expression(textOrRegex) {
+    let warned = false;
+    if (typeof textOrRegex === 'string') {
+        return {
+            description: `expression containing '${textOrRegex}'`,
+            // No syntaxKinds — walks all descendants
+            matches(node) {
+                if (!warned) {
+                    console.warn(`[eess] expression('${textOrRegex}') is a broad matcher. ` +
+                        `Prefer call(), access(), or newExpr() for precise matching.`);
+                    warned = true;
+                }
+                return node.getText().includes(textOrRegex);
+            },
+        };
+    }
+    return {
+        description: `expression matching ${String(textOrRegex)}`,
+        // No syntaxKinds — walks all descendants
+        matches(node) {
+            if (!warned) {
+                console.warn(`[eess] expression(${String(textOrRegex)}) is a broad matcher. ` +
+                    `Prefer call(), access(), or newExpr() for precise matching.`);
+                warned = true;
+            }
+            return textOrRegex.test(node.getText());
+        },
+    };
+}
+/**
+ * Match a PropertyAssignment by name and optional value.
+ *
+ * Targets `SyntaxKind.PropertyAssignment` for efficient traversal via
+ * `getDescendantsOfKind`. Does NOT match ShorthandPropertyAssignment
+ * (`{ schema }`) — those have no initializer.
+ *
+ * Value matching uses semantic comparison for primitives:
+ * - `boolean` — matches TrueKeyword / FalseKeyword
+ * - `number` — matches NumericLiteral via getLiteralValue()
+ * - `string` — matches StringLiteral via getLiteralValue() (no quotes needed)
+ * - `RegExp` — matches initializer getText() (raw text including quotes)
+ *
+ * @param name - Exact property name or regex for flexible matching.
+ * @param value - Optional value constraint. Omit for name-only matching.
+ *
+ * @example
+ * property('additionalProperties', true)   // matches additionalProperties: true
+ * property('type', 'object')               // matches type: 'object'
+ * property('maximum', 100)                 // matches maximum: 100
+ * property(/^additional/)                  // matches any property starting with 'additional'
+ * property('mode', /^'(strict|loose)'$/)   // matches mode: 'strict' or 'loose' (getText() includes quotes)
+ */
+/**
+ * Test whether an initializer matches the expected value.
+ */
+function matchPropertyValue(initializer, value) {
+    if (typeof value === 'boolean') {
+        const kind = initializer.getKind();
+        return value ? kind === SyntaxKind.TrueKeyword : kind === SyntaxKind.FalseKeyword;
+    }
+    if (typeof value === 'number') {
+        return Node.isNumericLiteral(initializer) && initializer.getLiteralValue() === value;
+    }
+    if (typeof value === 'string') {
+        return Node.isStringLiteral(initializer) && initializer.getLiteralValue() === value;
+    }
+    return value.test(initializer.getText());
+}
+/**
+ * Test whether a property assignment's name matches the expected pattern.
+ */
+function matchPropertyName(node, name) {
+    if (!Node.isPropertyAssignment(node))
+        return false;
+    if (node.getNameNode().getKind() === SyntaxKind.ComputedPropertyName)
+        return false;
+    const nameNode = node.getNameNode();
+    const propName = Node.isStringLiteral(nameNode) ? nameNode.getLiteralValue() : node.getName();
+    if (typeof name === 'string')
+        return propName === name;
+    return name.test(propName);
+}
+export function property(name, value) {
+    const nameDesc = typeof name === 'string' ? `'${name}'` : String(name);
+    const valueDesc = value === undefined ? '' : ` = ${String(value)}`;
+    const description = `property ${nameDesc}${valueDesc}`;
+    return {
+        description,
+        syntaxKinds: [SyntaxKind.PropertyAssignment],
+        matches(node) {
+            if (!matchPropertyName(node, name))
+                return false;
+            if (value === undefined)
+                return true;
+            const initializer = Node.isPropertyAssignment(node) ? node.getInitializer() : undefined;
+            if (!initializer)
+                return false;
+            return matchPropertyValue(initializer, value);
+        },
+    };
+}
+/**
+ * Default stub/deferred-work patterns found in comments.
+ * Matches common markers (see regex) and phrases like
+ * "not implemented" or "coming soon".
+ *
+ * Exported as a constant for use with `comment()`. Users can pass
+ * their own RegExp to `comment()` for narrower matching.
+ */
+export const STUB_PATTERNS = /\b(TODO|FIXME|HACK|XXX|STUB|DEFERRED|PLACEHOLDER)\b|\bnot\s+implemented\b|\bcoming\s+soon\b/i;
+/**
+ * Match comments attached to AST nodes.
+ *
+ * Unlike other matchers that test AST nodes, this matcher tests the
+ * leading and trailing comment ranges of each node. It uses
+ * `syntaxKinds: undefined` so the broad traversal path visits every node,
+ * and `matches(node)` checks that node's comment ranges.
+ *
+ * A Set tracks matched comment positions to avoid duplicates (the same
+ * comment may be visited as leading trivia of multiple nested nodes).
+ *
+ * @param pattern - String substring or RegExp to test against comment text.
+ *
+ * @example
+ * comment(/HACK/)                     // matches hack marker comments
+ * comment(STUB_PATTERNS)              // matches all common stub markers
+ * comment('HACK')                     // matches hack comments
+ */
+export function comment(pattern) {
+    // Dedup by (filePath, pos) — prevents the same comment from matching
+    // multiple times when visited as leading trivia of nested nodes.
+    // Using a composite string key avoids cross-file collisions.
+    const matchedComments = new Set();
+    function testComment(range) {
+        const text = range.getText();
+        if (typeof pattern === 'string') {
+            return text.includes(pattern);
+        }
+        // Reset lastIndex for stateful (g-flag) regexes
+        pattern.lastIndex = 0;
+        return pattern.test(text);
+    }
+    return {
+        description: typeof pattern === 'string'
+            ? `comment containing '${pattern}'`
+            : `comment matching ${String(pattern)}`,
+        // No syntaxKinds — broad traversal to visit all nodes and their comments
+        matches(node) {
+            const filePath = node.getSourceFile().getFilePath();
+            const ranges = [...node.getLeadingCommentRanges(), ...node.getTrailingCommentRanges()];
+            for (const range of ranges) {
+                const key = `${filePath}:${String(range.getPos())}`;
+                if (matchedComments.has(key))
+                    continue;
+                if (testComment(range)) {
+                    matchedComments.add(key);
+                    return true;
+                }
+            }
+            return false;
+        },
+    };
+}
+/**
+ * Extract the tag name from a JsxElement or JsxSelfClosingElement node.
+ */
+function getJsxTagName(node) {
+    if (Node.isJsxElement(node)) {
+        return node.getOpeningElement().getTagNameNode().getText();
+    }
+    if (Node.isJsxSelfClosingElement(node)) {
+        return node.getTagNameNode().getText();
+    }
+    return undefined;
+}
+/**
+ * Match a JSX element by tag name.
+ *
+ * Targets `JsxElement` (has children) and `JsxSelfClosingElement` (no children).
+ * This is a **tag-only** matcher — it cannot check attributes. Use the
+ * `jsxElements()` entry point for attribute-level rules.
+ *
+ * @param tagOrRegex - Exact tag name (e.g. 'div', 'Button') or regex.
+ *
+ * @example
+ * jsxElement('div')                    // matches <div>...</div> and <div />
+ * jsxElement('Button')                 // matches <Button>...</Button>
+ * jsxElement(/^motion\./)              // matches <motion.div>, <motion.span>, etc.
+ */
+export function jsxElement(tagOrRegex) {
+    if (typeof tagOrRegex === 'string') {
+        return {
+            description: `JSX element <${tagOrRegex}>`,
+            syntaxKinds: [SyntaxKind.JsxElement, SyntaxKind.JsxSelfClosingElement],
+            matches(node) {
+                const tag = getJsxTagName(node);
+                return tag === tagOrRegex;
+            },
+        };
+    }
+    return {
+        description: `JSX element matching ${String(tagOrRegex)}`,
+        syntaxKinds: [SyntaxKind.JsxElement, SyntaxKind.JsxSelfClosingElement],
+        matches(node) {
+            const tag = getJsxTagName(node);
+            if (tag === undefined)
+                return false;
+            return tagOrRegex.test(tag);
+        },
+    };
+}
+/**
+ * Match hardcoded JSX text content — the children of JSX elements.
+ *
+ * Where {@link jsxElement} matches elements by tag and the `jsxElements()`
+ * entry point handles attribute values, this matcher covers the remaining
+ * gap: literal text rendered as element children. Composes with
+ * `notContain()` for i18n-style rules ("no hardcoded user-facing text").
+ *
+ * Matches:
+ * - `JsxText` nodes with non-whitespace content (`<button>Save</button>`).
+ * - `JsxExpression` wrapping a bare string literal (`<div>{"Save"}</div>`)
+ *   or a no-substitution template (`` <div>{`Save`}</div> ``) — these render
+ *   identically to plain text and would otherwise be a trivial bypass.
+ *
+ * Does NOT match: inter-element whitespace, `{expr}` wrapping an identifier
+ * or call (`<div>{t("save")}</div>`), templates with substitution
+ * (`` <div>{`Hi ${name}`}</div> ``), or attribute values whether braced or
+ * quoted (`title={"Save"}`, `title="Save"`) — those belong to the
+ * `jsxElements()` entry point. No letter-presence filter is baked in —
+ * `<div>123</div>` matches; the matcher takes no options, so to narrow which
+ * text is flagged, scope the rule with folder/file predicates or
+ * `.excluding(...)`. Note: text inside translation wrappers like `<Trans>`
+ * also matches — scope those out the same way if your i18n setup uses them.
+ *
+ * @example
+ * modules(p)
+ *   .that()
+ *   .resideInFolder('src/components/**')
+ *   .should()
+ *   .notContain(jsxText())
+ *   .because('User-facing text must go through t()')
+ *   .check()
+ */
+export function jsxText() {
+    return {
+        description: 'JSX text content',
+        syntaxKinds: [SyntaxKind.JsxText, SyntaxKind.JsxExpression],
+        matches(node) {
+            if (Node.isJsxText(node)) {
+                return node.getLiteralText().trim().length > 0;
+            }
+            if (Node.isJsxExpression(node)) {
+                // A JsxExpression appears in two positions: as an element child
+                // (`<div>{"x"}</div>`) or as an attribute value (`<div title={"x"} />`).
+                // Attribute values are the domain of the `jsxElements()` entry point —
+                // only match child position (parent is a JsxElement or JsxFragment).
+                const parent = node.getParent();
+                if (!Node.isJsxElement(parent) && !Node.isJsxFragment(parent))
+                    return false;
+                const expr = node.getExpression();
+                if (!expr)
+                    return false;
+                if (Node.isStringLiteral(expr))
+                    return true;
+                if (Node.isNoSubstitutionTemplateLiteral(expr))
+                    return true;
+                return false;
+            }
+            return false;
+        },
+    };
+}
+/**
+ * Match type assertion expressions — both `as Type` and the legacy
+ * angle-bracket `<Type>value` form.
+ *
+ * By default, `as const` is excluded from matches (it narrows types rather
+ * than widening them, so it's idiomatic for literal preservation). The
+ * `allowConst` option does not affect angle-bracket assertions — those
+ * can't express `as const` and are always matched.
+ *
+ * Does NOT match `satisfies` expressions — those are validation, not
+ * assertions, and should not be banned.
+ *
+ * @example
+ * // Allow `as const` in user code (default)
+ * classes(p).should().notContain(typeAssertion()).check()
+ *
+ * @example
+ * // Ban `as const` too — no `as` expressions of any kind
+ * modules(p).should().notContain(typeAssertion({ allowConst: false })).check()
+ */
+export function typeAssertion(options) {
+    const allowConst = options?.allowConst ?? true;
+    return {
+        description: 'type assertion',
+        syntaxKinds: [SyntaxKind.AsExpression, SyntaxKind.TypeAssertionExpression],
+        matches(node) {
+            // Angle-bracket `<Type>value` — can't be `as const`, always matches
+            if (Node.isTypeAssertion(node))
+                return true;
+            if (!Node.isAsExpression(node))
+                return false;
+            if (!allowConst)
+                return true;
+            const typeNode = node.getTypeNode();
+            if (typeNode && Node.isTypeReference(typeNode)) {
+                const typeName = typeNode.getTypeName();
+                if (Node.isIdentifier(typeName) && typeName.getText() === 'const') {
+                    return false;
+                }
+            }
+            return true;
+        },
+    };
+}
+/**
+ * Match `!` non-null assertion expressions.
+ *
+ * @example
+ * functions(p).should().notContain(nonNullAssertion()).check()
+ */
+export function nonNullAssertion() {
+    return {
+        description: 'non-null assertion',
+        syntaxKinds: [SyntaxKind.NonNullExpression],
+        matches(node) {
+            return Node.isNonNullExpression(node);
+        },
+    };
+}
+//# sourceMappingURL=matchers.js.map

package/dist/helpers/matchers.js.map

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

package/dist/helpers/pattern.d.ts

@@ -0,0 +1,37 @@
+import type { TypeMatcher } from '../helpers/type-matchers.js';
+/**
+ * A shape constraint for a single property in a return type.
+ *
+ * - `string` — matched as regex against `Type.getText()` (e.g. `'number'`, `'string'`)
+ * - `'T[]'` — matches any array type regardless of element type
+ * - `TypeMatcher` — full programmatic control (reuse existing matchers)
+ */
+export type PropertyConstraint = string | TypeMatcher;
+/**
+ * A named architectural pattern that describes expected return type shape.
+ */
+export interface ArchPattern {
+    /** Human-readable pattern name, e.g. 'paginated-collection' */
+    readonly name: string;
+    /** Required properties and their type constraints on the return type */
+    readonly returnShape: Record<string, PropertyConstraint>;
+}
+/**
+ * Define a reusable architectural pattern.
+ *
+ * @example
+ * ```ts
+ * const paginatedCollection = definePattern('paginated-collection', {
+ *   returnShape: {
+ *     total: 'number',
+ *     skip: 'number',
+ *     limit: 'number',
+ *     items: 'T[]',
+ *   },
+ * })
+ * ```
+ */
+export declare function definePattern(name: string, options: {
+    returnShape: Record<string, PropertyConstraint>;
+}): ArchPattern;
+//# sourceMappingURL=pattern.d.ts.map

package/dist/helpers/pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern.d.ts","sourceRoot":"","sources":["../../src/helpers/pattern.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAA;AAE9D;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,WAAW,CAAA;AAErD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;CACzD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;CAAE,GAC3D,WAAW,CAKb"}

package/dist/helpers/pattern.js

@@ -0,0 +1,22 @@
+/**
+ * Define a reusable architectural pattern.
+ *
+ * @example
+ * ```ts
+ * const paginatedCollection = definePattern('paginated-collection', {
+ *   returnShape: {
+ *     total: 'number',
+ *     skip: 'number',
+ *     limit: 'number',
+ *     items: 'T[]',
+ *   },
+ * })
+ * ```
+ */
+export function definePattern(name, options) {
+    return {
+        name,
+        returnShape: options.returnShape,
+    };
+}
+//# sourceMappingURL=pattern.js.map

package/dist/helpers/pattern.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern.js","sourceRoot":"","sources":["../../src/helpers/pattern.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,OAA4D;IAE5D,OAAO;QACL,IAAI;QACJ,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAA;AACH,CAAC"}

package/dist/helpers/slice-graph.d.ts

@@ -0,0 +1,32 @@
+import type { SourceFile } from 'ts-morph';
+import type { Slice } from '../models/slice.js';
+/**
+ * An edge in the slice dependency graph.
+ * Represents: a file in `from` imports a file in `to`.
+ */
+export interface SliceEdge {
+    from: string;
+    to: string;
+}
+/**
+ * Build a reverse lookup map: file path -> slice name.
+ * Shared by buildSliceDependencyGraph and findSliceDependencyDetails.
+ */
+export declare function buildFileToSliceMap(slices: Slice[]): Map<string, string>;
+export declare function buildSliceDependencyGraph(slices: Slice[], fileToSlice?: Map<string, string>): SliceEdge[];
+/**
+ * Find which specific files cause a dependency from one slice to another.
+ * Used for detailed violation messages.
+ *
+ * @param slices - The resolved slices
+ * @param fromSliceName - Source slice name
+ * @param toSliceName - Target slice name
+ * @param fileToSlice - Pre-built file-to-slice map (optional, built internally if not provided)
+ * @returns Array of { sourceFile, importPath, importLine }
+ */
+export declare function findSliceDependencyDetails(slices: Slice[], fromSliceName: string, toSliceName: string, fileToSlice?: Map<string, string>): Array<{
+    sourceFile: SourceFile;
+    importPath: string;
+    importLine: number;
+}>;
+//# sourceMappingURL=slice-graph.d.ts.map

package/dist/helpers/slice-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slice-graph.d.ts","sourceRoot":"","sources":["../../src/helpers/slice-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAG/C;;;GAGG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;CACX;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAQxE;AAsCD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,KAAK,EAAE,EACf,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,SAAS,EAAE,CAcb;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,KAAK,EAAE,EACf,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,KAAK,CAAC;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAwB3E"}

package/dist/helpers/slice-graph.js

@@ -0,0 +1,89 @@
+import { getDependencyDecls } from '../core/module-dependencies.js';
+/**
+ * Build a reverse lookup map: file path -> slice name.
+ * Shared by buildSliceDependencyGraph and findSliceDependencyDetails.
+ */
+export function buildFileToSliceMap(slices) {
+    const fileToSlice = new Map();
+    for (const slice of slices) {
+        for (const file of slice.files) {
+            fileToSlice.set(file.getFilePath(), slice.name);
+        }
+    }
+    return fileToSlice;
+}
+/**
+ * Build a directed dependency graph between slices.
+ *
+ * For each file in each slice, resolve its imports. If an imported file
+ * belongs to a different slice, add a directed edge from the importing
+ * slice to the imported slice.
+ *
+ * @param slices - The resolved slices
+ * @param fileToSlice - Pre-built file-to-slice map (optional, built internally if not provided)
+ * @returns Unique directed edges between slices
+ */
+/**
+ * Collect unique slice edges from a single file's imports.
+ */
+function collectEdgesFromFile(file, sliceName, fileToSlice, edgeSet, edges) {
+    for (const importDecl of getDependencyDecls(file)) {
+        const resolved = importDecl.getModuleSpecifierSourceFile();
+        if (!resolved)
+            continue;
+        const targetSlice = fileToSlice.get(resolved.getFilePath());
+        if (targetSlice && targetSlice !== sliceName) {
+            const edgeKey = `${sliceName}->${targetSlice}`;
+            if (!edgeSet.has(edgeKey)) {
+                edgeSet.add(edgeKey);
+                edges.push({ from: sliceName, to: targetSlice });
+            }
+        }
+    }
+}
+export function buildSliceDependencyGraph(slices, fileToSlice) {
+    const map = fileToSlice ?? buildFileToSliceMap(slices);
+    // Collect unique edges
+    const edgeSet = new Set();
+    const edges = [];
+    for (const slice of slices) {
+        for (const file of slice.files) {
+            collectEdgesFromFile(file, slice.name, map, edgeSet, edges);
+        }
+    }
+    return edges;
+}
+/**
+ * Find which specific files cause a dependency from one slice to another.
+ * Used for detailed violation messages.
+ *
+ * @param slices - The resolved slices
+ * @param fromSliceName - Source slice name
+ * @param toSliceName - Target slice name
+ * @param fileToSlice - Pre-built file-to-slice map (optional, built internally if not provided)
+ * @returns Array of { sourceFile, importPath, importLine }
+ */
+export function findSliceDependencyDetails(slices, fromSliceName, toSliceName, fileToSlice) {
+    const map = fileToSlice ?? buildFileToSliceMap(slices);
+    const fromSlice = slices.find((s) => s.name === fromSliceName);
+    if (!fromSlice)
+        return [];
+    const details = [];
+    for (const file of fromSlice.files) {
+        for (const importDecl of getDependencyDecls(file)) {
+            const resolved = importDecl.getModuleSpecifierSourceFile();
+            if (!resolved)
+                continue;
+            const targetSlice = map.get(resolved.getFilePath());
+            if (targetSlice === toSliceName) {
+                details.push({
+                    sourceFile: file,
+                    importPath: resolved.getFilePath(),
+                    importLine: importDecl.getStartLineNumber(),
+                });
+            }
+        }
+    }
+    return details;
+}
+//# sourceMappingURL=slice-graph.js.map