@opensip-cli/graph 0.1.0

package/dist/rules/cycle.js

@@ -0,0 +1,166 @@
+/**
+ * graph:cycle — flag call-graph cycles (strongly-connected components of size
+ * ≥ 2) at function/SCC granularity. Reads the `scc` feature column (Phase C's
+ * Tarjan; NO in-rule cycle detection). Bounded + actionable per ADR-0001: the
+ * count reaches zero when every cycle is broken; the fix is "invert one
+ * dependency or extract the shared piece."
+ *
+ * Severity ladder (defaults from the dashboard's former SCCs view,
+ * `view-sccs.ts`: "size 2 usually fine; size 3+ spanning packages is a layering
+ * smell"):
+ *   - `sccSize === 1`         → no signal (not a cycle).
+ *   - `crossesPackages`       → base `high` (regardless of size — cross-package
+ *                               cycles are the most expensive to unwind; they
+ *                               win the ladder).
+ *   - `sccSize === 2`         → `config.cycleSize2Severity` (default `'off'` →
+ *                               no signal; `'low'` → base `low`).
+ *   - `sccSize >= cycleMinSize` (default 3) → base `medium`.
+ *
+ * One signal PER SCC (not per member) — anchored on the lowest-`qualifiedName`
+ * member occurrence so a single tangle never produces N findings. This is the
+ * function/SCC-granularity de-dup counterpart to `unexpected-coupling`'s
+ * package granularity (distinct `ruleId` + `code` → distinct fingerprints,
+ * cross-linked via metadata).
+ *
+ * Emitted severity routes through the opt-in `applySeverityOverride` clamp
+ * (ADR-0005).
+ */
+import { pkgOf } from '../resolve-callee.js';
+import { createGraphSignal } from './create-graph-signal.js';
+import { defineRule } from './define-rule.js';
+const DEFAULT_CYCLE_MIN_SIZE = 3;
+export const cycleRule = defineRule({
+    slug: 'graph:cycle',
+    defaultSeverity: 'warning',
+    featureDeps: ['scc'],
+    evaluate({ indexes, config, features }) {
+        // Absent feature table → emit nothing (SCC detection is Phase C's job;
+        // no in-rule Tarjan).
+        if (!features)
+            return [];
+        const minSize = config.cycleMinSize ?? DEFAULT_CYCLE_MIN_SIZE;
+        const size2 = config.cycleSize2Severity ?? 'off';
+        const signals = [];
+        for (const scc of features.scc) {
+            const base = bandFor(scc, minSize, size2);
+            if (base === undefined)
+                continue;
+            const anchor = anchorOccurrence(scc, indexes);
+            /* v8 ignore next */
+            if (!anchor)
+                continue;
+            // Skip a cycle whose members are ALL in test files — a recursive test
+            // helper or mutually-recursive fixtures are test code, not a production
+            // architecture concern (consistent with the test-file skip in the other
+            // graph rules). A cycle that includes ANY production member is kept.
+            if (isTestOnlyScc(scc, indexes))
+                continue;
+            // The distinct packages this SCC spans — the cross-link to
+            // graph:unexpected-coupling's per-package-pair-cycle signal. Only
+            // meaningful (more than one package) when the SCC crosses packages.
+            const spannedPackages = scc.crossesPackages ? packagesOf(scc, indexes) : undefined;
+            signals.push(createGraphSignal('graph:cycle', config, {
+                severity: base,
+                category: 'architecture',
+                message: `${anchor.simpleName} is part of a ${String(scc.sccSize)}-function call cycle${scc.crossesPackages ? ' spanning multiple packages' : ''}.`,
+                code: { file: anchor.filePath, line: anchor.line, column: anchor.column },
+                suggestion: 'Break the cycle: invert one dependency or extract the shared piece.',
+                metadata: {
+                    sccId: scc.id,
+                    sccSize: scc.sccSize,
+                    crossesPackages: scc.crossesPackages,
+                    qualifiedName: anchor.qualifiedName,
+                    // Cross-link to graph:unexpected-coupling's per-package-pair-cycle
+                    // signal: the distinct packages this cross-package SCC spans
+                    // (undefined for an intra-package cycle).
+                    relatedPackageCycle: spannedPackages,
+                    // Every member's source location (ADR-0014): a `@graph-ignore`
+                    // directive above ANY member waives this one-per-SCC finding, not
+                    // only the computed anchor line. Metadata is not fingerprinted, so
+                    // this is baseline-neutral.
+                    memberLocations: memberLocations(scc, indexes),
+                },
+            }));
+        }
+        return signals;
+    },
+});
+/**
+ * Resolve the SCC's severity band, or `undefined` for "no signal".
+ *  - size 1 → no signal;
+ *  - crossesPackages → `high` (wins regardless of size);
+ *  - size 2 → the configured size-2 posture (`off` → none, `low` → `low`);
+ *  - size ≥ minSize → `medium`;
+ *  - otherwise (e.g. a size-2 with size2 off, or a sub-minSize size ≥ 3 when
+ *    minSize was raised) → no signal.
+ */
+function bandFor(scc, minSize, size2) {
+    if (scc.sccSize <= 1)
+        return undefined;
+    if (scc.crossesPackages)
+        return 'high';
+    if (scc.sccSize === 2)
+        return size2 === 'low' ? 'low' : undefined;
+    if (scc.sccSize >= minSize)
+        return 'medium';
+    return undefined;
+}
+/**
+ * The lowest-`qualifiedName` member occurrence of the SCC — the stable anchor
+ * for the one-per-SCC signal (mirrors duplicated-function-body's
+ * `lowestByQualifiedName`). Members are occIds
+ * (`${filePath}:${line}:${column}`); resolve each via `byOccId`.
+ */
+function anchorOccurrence(scc, indexes) {
+    let anchor;
+    for (const id of scc.members) {
+        const occ = indexes.byOccId.get(id);
+        if (!occ)
+            continue;
+        if (!anchor || occ.qualifiedName < anchor.qualifiedName)
+            anchor = occ;
+    }
+    return anchor;
+}
+/**
+ * True when EVERY resolvable member of the SCC lives in a test file (a cycle
+ * entirely within test code). Returns false the moment any member is a
+ * production occurrence, so a cycle that touches production is still reported.
+ */
+function isTestOnlyScc(scc, indexes) {
+    let sawMember = false;
+    for (const id of scc.members) {
+        const occ = indexes.byOccId.get(id);
+        if (!occ)
+            continue;
+        sawMember = true;
+        if (!occ.inTestFile)
+            return false;
+    }
+    return sawMember;
+}
+/** The sorted distinct packages an SCC's resolvable members belong to. */
+function packagesOf(scc, indexes) {
+    const packages = new Set();
+    for (const id of scc.members) {
+        const occ = indexes.byOccId.get(id);
+        if (occ)
+            packages.add(pkgOf(occ));
+    }
+    return [...packages].sort();
+}
+/**
+ * Every resolvable member's `{ file, line }` — the candidate locations a
+ * `@graph-ignore` directive may target to waive this SCC (ADR-0014). Consumed
+ * by graph's suppression `locate()` so a directive above any member matches.
+ */
+function memberLocations(scc, indexes) {
+    const locations = [];
+    for (const id of scc.members) {
+        const occ = indexes.byOccId.get(id);
+        if (occ?.filePath)
+            locations.push({ file: occ.filePath, line: occ.line });
+    }
+    return locations;
+}
+//# sourceMappingURL=cycle.js.map

package/dist/rules/cycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle.js","sourceRoot":"","sources":["../../src/rules/cycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAK9C,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAEjC,MAAM,CAAC,MAAM,SAAS,GAAG,UAAU,CAAC;IAClC,IAAI,EAAE,aAAa;IACnB,eAAe,EAAE,SAAS;IAC1B,WAAW,EAAE,CAAC,KAAK,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE;QACpC,uEAAuE;QACvE,sBAAsB;QACtB,IAAI,CAAC,QAAQ;YAAE,OAAO,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,MAAM,CAAC,YAAY,IAAI,sBAAsB,CAAC;QAC9D,MAAM,KAAK,GAAG,MAAM,CAAC,kBAAkB,IAAI,KAAK,CAAC;QAEjD,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,GAAG,EAAE,CAAC;YAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;YAC1C,IAAI,IAAI,KAAK,SAAS;gBAAE,SAAS;YACjC,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC9C,oBAAoB;YACpB,IAAI,CAAC,MAAM;gBAAE,SAAS;YACtB,sEAAsE;YACtE,wEAAwE;YACxE,wEAAwE;YACxE,qEAAqE;YACrE,IAAI,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC;gBAAE,SAAS;YAC1C,2DAA2D;YAC3D,kEAAkE;YAClE,oEAAoE;YACpE,MAAM,eAAe,GAAG,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACnF,OAAO,CAAC,IAAI,CACV,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE;gBACvC,QAAQ,EAAE,IAAI;gBACd,QAAQ,EAAE,cAAc;gBACxB,OAAO,EAAE,GAAG,MAAM,CAAC,UAAU,iBAAiB,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,uBAAuB,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,EAAE,GAAG;gBACnJ,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;gBACzE,UAAU,EAAE,qEAAqE;gBACjF,QAAQ,EAAE;oBACR,KAAK,EAAE,GAAG,CAAC,EAAE;oBACb,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,eAAe,EAAE,GAAG,CAAC,eAAe;oBACpC,aAAa,EAAE,MAAM,CAAC,aAAa;oBACnC,mEAAmE;oBACnE,6DAA6D;oBAC7D,0CAA0C;oBAC1C,mBAAmB,EAAE,eAAe;oBACpC,+DAA+D;oBAC/D,kEAAkE;oBAClE,mEAAmE;oBACnE,4BAA4B;oBAC5B,eAAe,EAAE,eAAe,CAAC,GAAG,EAAE,OAAO,CAAC;iBAC/C;aACF,CAAC,CACH,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,SAAS,OAAO,CACd,GAAgB,EAChB,OAAe,EACf,KAAoB;IAEpB,IAAI,GAAG,CAAC,OAAO,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACvC,IAAI,GAAG,CAAC,eAAe;QAAE,OAAO,MAAM,CAAC;IACvC,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC;QAAE,OAAO,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,IAAI,GAAG,CAAC,OAAO,IAAI,OAAO;QAAE,OAAO,QAAQ,CAAC;IAC5C,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,GAAgB,EAAE,OAAgB;IAC1D,IAAI,MAAsC,CAAC;IAC3C,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa;YAAE,MAAM,GAAG,GAAG,CAAC;IACxE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,GAAgB,EAAE,OAAgB;IACvD,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,SAAS,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,GAAG,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;IACpC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,0EAA0E;AAC1E,SAAS,UAAU,CAAC,GAAgB,EAAE,OAAgB;IACpD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,GAAG;YAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CACtB,GAAgB,EAChB,OAAgB;IAEhB,MAAM,SAAS,GAAqC,EAAE,CAAC;IACvD,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,GAAG,EAAE,QAAQ;YAAE,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/rules/cycle.memberlocations.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Focused coverage for `graph:cycle`'s `metadata.memberLocations` (ADR-0014):
+ * the per-SCC signal must carry every resolvable member's `{ file, line }` so
+ * graph's suppression `locate()` can waive the one-per-SCC finding via a
+ * `@graph-ignore` directive above ANY member — not only the computed anchor.
+ *
+ * Drives the rule's `evaluate` directly with a synthetic `scc` feature, mirroring
+ * the `catalogOf` / `buildIndexes` harness in `__tests__/rule-behaviors.test.ts`.
+ */
+export {};
+//# sourceMappingURL=cycle.memberlocations.test.d.ts.map

package/dist/rules/cycle.memberlocations.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle.memberlocations.test.d.ts","sourceRoot":"","sources":["../../src/rules/cycle.memberlocations.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/rules/cycle.memberlocations.test.js

@@ -0,0 +1,84 @@
+/**
+ * Focused coverage for `graph:cycle`'s `metadata.memberLocations` (ADR-0014):
+ * the per-SCC signal must carry every resolvable member's `{ file, line }` so
+ * graph's suppression `locate()` can waive the one-per-SCC finding via a
+ * `@graph-ignore` directive above ANY member — not only the computed anchor.
+ *
+ * Drives the rule's `evaluate` directly with a synthetic `scc` feature, mirroring
+ * the `catalogOf` / `buildIndexes` harness in `__tests__/rule-behaviors.test.ts`.
+ */
+import { describe, expect, it } from 'vitest';
+import { buildIndexes } from '../pipeline/indexes.js';
+import { cycleRule } from './cycle.js';
+function occ(over) {
+    return {
+        qualifiedName: `${over.filePath}.${over.simpleName}`,
+        column: 0,
+        endLine: over.line + 1,
+        kind: 'function-declaration',
+        params: [],
+        returnType: null,
+        enclosingClass: null,
+        decorators: [],
+        visibility: 'exported',
+        inTestFile: false,
+        definedInGenerated: false,
+        calls: [],
+        ...over,
+    };
+}
+function catalogOf(occs) {
+    const functions = {};
+    for (const o of occs) {
+        const bucket = functions[o.simpleName];
+        if (bucket)
+            bucket.push(o);
+        else
+            functions[o.simpleName] = [o];
+    }
+    return {
+        version: '3.0',
+        tool: 'graph',
+        language: 'typescript',
+        builtAt: 'x',
+        cacheKey: 'k',
+        resolutionMode: 'exact',
+        functions,
+    };
+}
+function featuresWith(scc) {
+    return {
+        function: new Map(),
+        package: new Map(),
+        scc: [scc],
+        edge: [],
+    };
+}
+const EMPTY_CONFIG = {};
+describe('cycleRule memberLocations', () => {
+    it('attaches a non-empty memberLocations array covering the SCC members', () => {
+        // A 3-member intra-package cycle (size ≥ default cycleMinSize → medium band).
+        const a = occ({ bodyHash: 'A', simpleName: 'a', filePath: 'src/a.ts', line: 3 });
+        const b = occ({ bodyHash: 'B', simpleName: 'b', filePath: 'src/b.ts', line: 7 });
+        const c = occ({ bodyHash: 'C', simpleName: 'c', filePath: 'src/c.ts', line: 11 });
+        const catalog = catalogOf([a, b, c]);
+        // Members are occIds (`${filePath}:${line}:${column}`), resolved via byOccId.
+        const scc = {
+            id: 'scc:src/a.ts:3:0',
+            members: ['src/a.ts:3:0', 'src/b.ts:7:0', 'src/c.ts:11:0'],
+            sccSize: 3,
+            crossesPackages: false,
+        };
+        const signals = cycleRule.evaluate(catalog, buildIndexes(catalog), EMPTY_CONFIG, undefined, featuresWith(scc));
+        expect(signals).toHaveLength(1);
+        const members = signals[0]?.metadata.memberLocations;
+        expect(Array.isArray(members)).toBe(true);
+        expect(members).toEqual(expect.arrayContaining([
+            { file: 'src/a.ts', line: 3 },
+            { file: 'src/b.ts', line: 7 },
+            { file: 'src/c.ts', line: 11 },
+        ]));
+        expect(members.length).toBe(3);
+    });
+});
+//# sourceMappingURL=cycle.memberlocations.test.js.map

package/dist/rules/cycle.memberlocations.test.js.map

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

package/dist/rules/define-rule.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `defineRule` — ergonomic factory wrapping the existing `Rule` interface.
+ *
+ * Mirrors fitness's `defineCheck`: the author writes a single
+ * `evaluate(data)` taking a dataset object `{ catalog, indexes, config,
+ * hints?, features? }` instead of the legacy positional
+ * `(catalog, indexes, config, hints?)` signature. The factory validates
+ * metadata, freezes the result, and adapts the object form back to the
+ * positional `Rule.evaluate` the orchestrator calls
+ * (`orchestrate.ts:217`) — so the orchestrator, registry, and every
+ * existing test stay untouched (the factory returns the *existing* `Rule`
+ * interface; there is no `Rule2`).
+ *
+ * **Identity-preserving.** `defineRule` adds no behavior beyond the
+ * positional→object adapter — slug / `ruleId` / emitted signals are
+ * whatever the author's `evaluate` body produces, byte-for-byte.
+ *
+ * **Plan C — features populated.** The dataset object carries an optional
+ * `features?` slot typed as the engine-computed `FeatureTable`. Plan C
+ * populates it (via the orchestrator's features stage + the positional 5th
+ * `evaluate` arg this factory now threads through); Plan D rules read it.
+ * The slot is still optional so 3/4-arg test calls and the features-absent
+ * fallback path stay valid.
+ */
+import type { Catalog, FeatureColumn, FeatureTable, GraphConfig, Indexes, Rule, RuleHints } from '../types.js';
+import type { Signal } from '@opensip-cli/core';
+/**
+ * The engine-computed feature columns attached to the dataset. Plan B
+ * reserved this as an empty placeholder; Plan C points it at the real
+ * {@link FeatureTable}. Retained as a named alias because it is on the
+ * engine's public barrel.
+ */
+export type GraphFeatures = FeatureTable;
+/**
+ * The dataset object handed to a `defineRule` author's `evaluate`. Parallels
+ * `defineCheck`'s `(content, filePath)`: "give the author the data." Object
+ * form is extensible — Plan C populates `features` with no signature churn.
+ */
+export interface RuleDataset {
+    readonly catalog: Catalog;
+    readonly indexes: Indexes;
+    readonly config: GraphConfig;
+    readonly hints?: RuleHints;
+    /** Engine-computed feature columns (Plan C). Present when the orchestrator
+     *  ran the features stage; `undefined` for 3/4-arg test calls. */
+    readonly features?: FeatureTable;
+}
+/** Author-facing config for `defineRule`. */
+export interface DefineRuleConfig {
+    /** Rule slug, e.g. "graph:orphan-subtree". Must start with "graph:". */
+    readonly slug: string;
+    readonly defaultSeverity: 'error' | 'warning';
+    /**
+     * Feature columns this rule reads. Surfaced onto the built `Rule` so the
+     * orchestrator's `unionFeatureDeps` computes them (lazy/needed-only).
+     */
+    readonly featureDeps?: readonly FeatureColumn[];
+    readonly evaluate: (data: RuleDataset) => readonly Signal[];
+}
+/**
+ * Build a `Rule` from an author-facing config. Validates metadata, freezes,
+ * and adapts the positional `evaluate(catalog, indexes, config, hints)`
+ * call shape (the orchestrator boundary) to the dataset-object form the
+ * author wrote. The adapter is the only behavioral code in the factory.
+ */
+export declare function defineRule(config: DefineRuleConfig): Rule;
+//# sourceMappingURL=define-rule.d.ts.map

package/dist/rules/define-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-rule.d.ts","sourceRoot":"","sources":["../../src/rules/define-rule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,YAAY,EACZ,WAAW,EACX,OAAO,EACP,IAAI,EACJ,SAAS,EACV,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC;AAEzC;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B;sEACkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;CAClC;AAED,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,eAAe,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,SAAS,MAAM,EAAE,CAAC;CAC7D;AAID;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAkDzD"}

package/dist/rules/define-rule.js

@@ -0,0 +1,66 @@
+/**
+ * `defineRule` — ergonomic factory wrapping the existing `Rule` interface.
+ *
+ * Mirrors fitness's `defineCheck`: the author writes a single
+ * `evaluate(data)` taking a dataset object `{ catalog, indexes, config,
+ * hints?, features? }` instead of the legacy positional
+ * `(catalog, indexes, config, hints?)` signature. The factory validates
+ * metadata, freezes the result, and adapts the object form back to the
+ * positional `Rule.evaluate` the orchestrator calls
+ * (`orchestrate.ts:217`) — so the orchestrator, registry, and every
+ * existing test stay untouched (the factory returns the *existing* `Rule`
+ * interface; there is no `Rule2`).
+ *
+ * **Identity-preserving.** `defineRule` adds no behavior beyond the
+ * positional→object adapter — slug / `ruleId` / emitted signals are
+ * whatever the author's `evaluate` body produces, byte-for-byte.
+ *
+ * **Plan C — features populated.** The dataset object carries an optional
+ * `features?` slot typed as the engine-computed `FeatureTable`. Plan C
+ * populates it (via the orchestrator's features stage + the positional 5th
+ * `evaluate` arg this factory now threads through); Plan D rules read it.
+ * The slot is still optional so 3/4-arg test calls and the features-absent
+ * fallback path stay valid.
+ */
+import { ValidationError } from '@opensip-cli/core';
+const VALIDATION_CODE = 'VALIDATION.GRAPH.RULE';
+/**
+ * Build a `Rule` from an author-facing config. Validates metadata, freezes,
+ * and adapts the positional `evaluate(catalog, indexes, config, hints)`
+ * call shape (the orchestrator boundary) to the dataset-object form the
+ * author wrote. The adapter is the only behavioral code in the factory.
+ */
+export function defineRule(config) {
+    if (typeof config.slug !== 'string' ||
+        config.slug.length === 0 ||
+        !config.slug.startsWith('graph:')) {
+        // @fitness-ignore-next-line result-pattern-consistency -- authoring-time programmer error: invalid rule metadata
+        throw new ValidationError(`defineRule: 'slug' must be a non-empty string starting with 'graph:' (got ${JSON.stringify(config.slug)})`, {
+            code: VALIDATION_CODE,
+        });
+    }
+    if (config.defaultSeverity !== 'error' && config.defaultSeverity !== 'warning') {
+        // @fitness-ignore-next-line result-pattern-consistency -- authoring-time programmer error: invalid rule metadata
+        throw new ValidationError(`defineRule: 'defaultSeverity' must be 'error' or 'warning' (got ${JSON.stringify(config.defaultSeverity)})`, {
+            code: VALIDATION_CODE,
+        });
+    }
+    if (typeof config.evaluate !== 'function') {
+        // @fitness-ignore-next-line result-pattern-consistency -- authoring-time programmer error: invalid rule metadata
+        throw new ValidationError(`defineRule: 'evaluate' must be a function for rule '${config.slug}'`, {
+            code: VALIDATION_CODE,
+        });
+    }
+    const rule = {
+        slug: config.slug,
+        defaultSeverity: config.defaultSeverity,
+        ...(config.featureDeps ? { featureDeps: config.featureDeps } : {}),
+        evaluate(catalog, indexes, ruleConfig, hints, features) {
+            // The orchestrator threads the engine-computed FeatureTable as the 5th
+            // positional arg (Plan C); `features` is undefined on 3/4-arg test calls.
+            return config.evaluate({ catalog, indexes, config: ruleConfig, hints, features });
+        },
+    };
+    return Object.freeze(rule);
+}
+//# sourceMappingURL=define-rule.js.map

package/dist/rules/define-rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-rule.js","sourceRoot":"","sources":["../../src/rules/define-rule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAiDpD,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,MAAwB;IACjD,IACE,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;QAC/B,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QACxB,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EACjC,CAAC;QACD,iHAAiH;QACjH,MAAM,IAAI,eAAe,CACvB,6EAA6E,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAC3G;YACE,IAAI,EAAE,eAAe;SACtB,CACF,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,eAAe,KAAK,OAAO,IAAI,MAAM,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QAC/E,iHAAiH;QACjH,MAAM,IAAI,eAAe,CACvB,mEAAmE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,eAAe,CAAC,GAAG,EAC5G;YACE,IAAI,EAAE,eAAe;SACtB,CACF,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;QAC1C,iHAAiH;QACjH,MAAM,IAAI,eAAe,CACvB,uDAAuD,MAAM,CAAC,IAAI,GAAG,EACrE;YACE,IAAI,EAAE,eAAe;SACtB,CACF,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAS;QACjB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,QAAQ,CACN,OAAgB,EAChB,OAAgB,EAChB,UAAuB,EACvB,KAAiB,EACjB,QAAuB;YAEvB,uEAAuE;YACvE,0EAA0E;YAC1E,OAAO,MAAM,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QACpF,CAAC;KACF,CAAC;IACF,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/rules/duplicated-function-body.d.ts

@@ -0,0 +1,40 @@
+/**
+ * graph:duplicated-function-body — group catalog entries whose body
+ * normalizes to the same hash and report duplicate bodies. The rule has
+ * two complementary code paths under one slug:
+ *
+ *   1. **Per-instance (size-gated).** A "duplicate" is two or more
+ *      functions whose normalized body is byte-identical
+ *      (whitespace/comment normalization handled by hashFunctionBody).
+ *      Two thresholds filter out non-actionable hits:
+ *
+ *        - minDuplicateBodyLines (default 5): the source span must be at
+ *          least this many lines.
+ *        - minDuplicateBodySize  (default 200): the *normalized* body
+ *          (post comment-strip + whitespace-collapse) must be at least
+ *          this many characters. This catches the common case of a
+ *          `defineCheck({ ... analyze(content) { return analyzeFile(...) } })`
+ *          wrapper where the source spans 8+ lines but the executable
+ *          body is only ~80 characters once normalized — structurally
+ *          identical to every other thin wrapper, but never an actionable
+ *          refactor target.
+ *
+ *      Emits N-1 signals per group (one per non-primary occurrence).
+ *
+ *   2. **Aggregate (cross-package).** For each body hash present in
+ *      ≥ minCrossPackageDuplicatePackages (default 3) DISTINCT packages
+ *      (via `pkgOf`), the rule emits ONE aggregate signal naming the
+ *      packages and SUPPRESSES the per-instance signals for that same hash
+ *      (no double-reporting). Bodies that don't reach N packages flow
+ *      through path (1) unchanged.
+ *
+ *      This path applies a LIGHTER, body-size-only floor
+ *      (`minCrossPackageDuplicateBodySize`, default 80 chars — no line floor)
+ *      rather than the per-instance floor: a *small* body copied across
+ *      packages is exactly what this path exists to catch, so the floor is
+ *      tuned only to drop TRIVIAL bodies (empty DI-constructor shims,
+ *      one-line getters, thin delegators) that are never consolidation
+ *      targets, while keeping genuinely-small shared utilities visible.
+ */
+export declare const duplicatedFunctionBodyRule: import("../types.js").Rule;
+//# sourceMappingURL=duplicated-function-body.d.ts.map

package/dist/rules/duplicated-function-body.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplicated-function-body.d.ts","sourceRoot":"","sources":["../../src/rules/duplicated-function-body.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAoBH,eAAO,MAAM,0BAA0B,4BA0DrC,CAAC"}