@selvakumaresra/specship 0.9.0 → 0.10.0

package/dist/fitness/fitness.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Architecture-fitness functions (REQ-FITNESS-001 / 002).
+ *
+ * Evaluates declarative architecture rules against the knowledge graph's
+ * dependency edges and reports concrete violations. Three rule types — forbidden
+ * dependency, layering allow-list, and module isolation (leaf/sink) — each an
+ * edge constraint. Selectors are globs over the project-relative file path
+ * (picomatch), so "module/dir A" addresses cleanly across languages.
+ *
+ * Deterministic (sorted output). A rule whose selector matches no node is
+ * reported as a CONFIG ERROR, never a silent pass (REQ-FITNESS-002.A3) — a typo
+ * can't produce a false-green. Pure read over QueryBuilder.
+ *
+ * Realizes the second harness-engineering expansion lane (REQ-STRATEGY-002).
+ */
+import { QueryBuilder } from '../db/queries';
+/** A glob over the project-relative file path (e.g. `src/ui/**`). */
+export type Selector = string;
+export interface ForbiddenRule {
+    type: 'forbidden';
+    name: string;
+    /** Dependencies FROM nodes matching this selector… */
+    from: Selector;
+    /** …TO nodes matching this selector are violations. */
+    to: Selector;
+}
+export interface LayersRule {
+    type: 'layers';
+    name: string;
+    /** layer name → selector that assigns nodes to it (first match wins, config order). */
+    layers: Record<string, Selector>;
+    /** layer name → layers it MAY depend on. Same-layer is always allowed. */
+    allow: Record<string, string[]>;
+}
+export interface IsolationRule {
+    type: 'isolation';
+    name: string;
+    module: Selector;
+    /** leaf: nothing outside may depend INTO the module. sink: it may depend on nothing outside. */
+    mode: 'leaf' | 'sink';
+}
+export type FitnessRule = ForbiddenRule | LayersRule | IsolationRule;
+export interface FitnessViolation {
+    rule: string;
+    ruleType: FitnessRule['type'];
+    source: string;
+    target: string;
+    location: string;
+    edgeKind: string;
+    detail: string;
+}
+export interface FitnessConfigError {
+    rule: string;
+    message: string;
+}
+export interface FitnessReport {
+    ruleCount: number;
+    violations: FitnessViolation[];
+    configErrors: FitnessConfigError[];
+    /** True when there are no violations AND no config errors. */
+    clean: boolean;
+}
+/**
+ * Evaluate the rules against the graph. Pure read.
+ */
+export declare function evaluateFitness(queries: QueryBuilder, rules: FitnessRule[]): FitnessReport;
+/** Default name of the checked-in project config file at the project root. */
+export declare const FITNESS_CONFIG_FILE = "specship.config.json";
+/**
+ * Load fitness rules from the checked-in `specship.config.json` (`fitness.rules`).
+ * Missing/unparseable config → no rules. Each entry is taken as-is; an invalid
+ * shape surfaces later as a config error during evaluation.
+ */
+export declare function loadFitnessRules(projectRoot: string): FitnessRule[];
+//# sourceMappingURL=fitness.d.ts.map

package/dist/fitness/fitness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fitness.d.ts","sourceRoot":"","sources":["../../src/fitness/fitness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7C,qEAAqE;AACrE,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,IAAI,EAAE,QAAQ,CAAC;IACf,uDAAuD;IACvD,EAAE,EAAE,QAAQ,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACjC,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,QAAQ,CAAC;IACjB,gGAAgG;IAChG,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,UAAU,GAAG,aAAa,CAAC;AAErE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC,8DAA8D;IAC9D,KAAK,EAAE,OAAO,CAAC;CAChB;AAWD;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,aAAa,CAoE1F;AAkDD,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,EAAE,CAgBnE"}

package/dist/fitness/fitness.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * Architecture-fitness functions (REQ-FITNESS-001 / 002).
+ *
+ * Evaluates declarative architecture rules against the knowledge graph's
+ * dependency edges and reports concrete violations. Three rule types — forbidden
+ * dependency, layering allow-list, and module isolation (leaf/sink) — each an
+ * edge constraint. Selectors are globs over the project-relative file path
+ * (picomatch), so "module/dir A" addresses cleanly across languages.
+ *
+ * Deterministic (sorted output). A rule whose selector matches no node is
+ * reported as a CONFIG ERROR, never a silent pass (REQ-FITNESS-002.A3) — a typo
+ * can't produce a false-green. Pure read over QueryBuilder.
+ *
+ * Realizes the second harness-engineering expansion lane (REQ-STRATEGY-002).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FITNESS_CONFIG_FILE = void 0;
+exports.evaluateFitness = evaluateFitness;
+exports.loadFitnessRules = loadFitnessRules;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const picomatch_1 = __importDefault(require("picomatch"));
+/** Edge kinds that are real dependencies (exclude structural containment/exports). */
+function isDepEdge(kind) {
+    return kind !== 'contains' && kind !== 'exports';
+}
+function cmp(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Evaluate the rules against the graph. Pure read.
+ */
+function evaluateFitness(queries, rules) {
+    const nodes = queries.getAllNodes();
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const files = [...new Set(nodes.map((n) => n.filePath))];
+    const violations = [];
+    const configErrors = [];
+    // A selector is "live" if at least one indexed file matches it.
+    const matcherCache = new Map();
+    const matcher = (sel) => {
+        let m = matcherCache.get(sel);
+        if (!m) {
+            m = (0, picomatch_1.default)(sel, { dot: true });
+            matcherCache.set(sel, m);
+        }
+        return m;
+    };
+    const selectorMatchesAny = (sel) => {
+        const m = matcher(sel);
+        return files.some((f) => m(f));
+    };
+    // Pre-validate selectors → config errors (REQ-FITNESS-002.A3).
+    const liveRules = [];
+    for (const rule of rules) {
+        const dead = [];
+        if (rule.type === 'forbidden') {
+            if (!selectorMatchesAny(rule.from))
+                dead.push(`from: "${rule.from}"`);
+            if (!selectorMatchesAny(rule.to))
+                dead.push(`to: "${rule.to}"`);
+        }
+        else if (rule.type === 'isolation') {
+            if (!selectorMatchesAny(rule.module))
+                dead.push(`module: "${rule.module}"`);
+        }
+        else if (rule.type === 'layers') {
+            for (const [layer, sel] of Object.entries(rule.layers)) {
+                if (!selectorMatchesAny(sel))
+                    dead.push(`layer ${layer}: "${sel}"`);
+            }
+        }
+        if (dead.length) {
+            configErrors.push({ rule: rule.name, message: `selector matches no indexed file — ${dead.join(', ')}` });
+        }
+        else {
+            liveRules.push(rule);
+        }
+    }
+    if (liveRules.length > 0) {
+        for (const n of nodes) {
+            const out = queries.getOutgoingEdges(n.id);
+            for (const e of out) {
+                if (!isDepEdge(e.kind))
+                    continue;
+                const tgt = byId.get(e.target);
+                if (!tgt)
+                    continue;
+                const loc = `${n.filePath}:${n.startLine ?? 0}`;
+                for (const rule of liveRules) {
+                    const v = evalEdge(rule, n, tgt, e, loc, matcher);
+                    if (v)
+                        violations.push(v);
+                }
+            }
+        }
+    }
+    violations.sort((a, b) => cmp(a.rule, b.rule) || cmp(a.location, b.location) || cmp(a.source, b.source) || cmp(a.target, b.target));
+    configErrors.sort((a, b) => cmp(a.rule, b.rule) || cmp(a.message, b.message));
+    return {
+        ruleCount: rules.length,
+        violations,
+        configErrors,
+        clean: violations.length === 0 && configErrors.length === 0,
+    };
+}
+function evalEdge(rule, src, tgt, edge, loc, matcher) {
+    const base = { rule: rule.name, ruleType: rule.type, source: src.qualifiedName, target: tgt.qualifiedName, location: loc, edgeKind: edge.kind };
+    if (rule.type === 'forbidden') {
+        if (matcher(rule.from)(src.filePath) && matcher(rule.to)(tgt.filePath)) {
+            return { ...base, detail: `forbidden dependency: ${rule.from} → ${rule.to}` };
+        }
+        return null;
+    }
+    if (rule.type === 'isolation') {
+        const inMod = matcher(rule.module);
+        const srcIn = inMod(src.filePath);
+        const tgtIn = inMod(tgt.filePath);
+        if (rule.mode === 'leaf' && tgtIn && !srcIn) {
+            return { ...base, detail: `${rule.module} is a leaf — nothing outside may depend into it` };
+        }
+        if (rule.mode === 'sink' && srcIn && !tgtIn) {
+            return { ...base, detail: `${rule.module} is a sink — it may depend on nothing outside` };
+        }
+        return null;
+    }
+    // layers
+    const layerOf = (file) => {
+        for (const [layer, sel] of Object.entries(rule.layers)) {
+            if (matcher(sel)(file))
+                return layer;
+        }
+        return null;
+    };
+    const ls = layerOf(src.filePath);
+    const lt = layerOf(tgt.filePath);
+    if (ls && lt && ls !== lt) {
+        const allowed = rule.allow[ls] ?? [];
+        if (!allowed.includes(lt)) {
+            return { ...base, detail: `layer "${ls}" may not depend on "${lt}" (allowed: ${allowed.length ? allowed.join(', ') : 'none'})` };
+        }
+    }
+    return null;
+}
+/** Default name of the checked-in project config file at the project root. */
+exports.FITNESS_CONFIG_FILE = 'specship.config.json';
+/**
+ * Load fitness rules from the checked-in `specship.config.json` (`fitness.rules`).
+ * Missing/unparseable config → no rules. Each entry is taken as-is; an invalid
+ * shape surfaces later as a config error during evaluation.
+ */
+function loadFitnessRules(projectRoot) {
+    try {
+        const raw = fs.readFileSync(path.join(projectRoot, exports.FITNESS_CONFIG_FILE), 'utf-8');
+        const cfg = JSON.parse(raw);
+        const rules = cfg?.fitness?.rules;
+        if (Array.isArray(rules)) {
+            return rules.filter((r) => !!r && typeof r === 'object' && typeof r.name === 'string'
+                && ['forbidden', 'layers', 'isolation'].includes(r.type ?? ''));
+        }
+    }
+    catch {
+        // no config / unparseable → no rules
+    }
+    return [];
+}
+//# sourceMappingURL=fitness.js.map

package/dist/fitness/fitness.js.map

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

package/dist/graph/maintainability.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Maintainability harness (REQ-MAINT-001).
+ *
+ * Derives four maintainability signals from the existing knowledge graph, with
+ * NO additional file parse — coupling, size hotspots, dependency cycles, and
+ * dead-code candidates. Pure read over `QueryBuilder`; deterministic (every
+ * output array is sorted by a stable key), so a re-run on an unchanged index is
+ * byte-identical and the report can underpin a future CI gate (REQ-STRATEGY-003).
+ *
+ * Realizes the first harness-engineering expansion lane (REQ-STRATEGY-001).
+ */
+import { QueryBuilder } from '../db/queries';
+import { NodeKind } from '../types';
+/** Flag thresholds. Defaults work out of the box; a project may override (REQ-MAINT-002). */
+export interface MaintainabilityThresholds {
+    /** A symbol/file with fan-in or fan-out ≥ this is a coupling hotspot. */
+    highDegree: number;
+    /** A symbol whose line span ≥ this is oversized. */
+    largeSymbolLines: number;
+    /** A file with ≥ this many defined symbols is a god-file. */
+    godFileSymbols: number;
+}
+export declare const DEFAULT_THRESHOLDS: MaintainabilityThresholds;
+/**
+ * Generated / vendored files excluded from the analysis by default — they aren't
+ * source-of-truth, so flagging them is noise (e.g. a bundled `chunk-*.js` shows
+ * as a huge coupling hub, a `.d.ts` as dead code). A project may add more via
+ * `maintainability.exclude` in specship.config.json. Globs over the
+ * project-relative file path.
+ */
+export declare const DEFAULT_EXCLUDE: string[];
+export interface CouplingFinding {
+    nodeId: string;
+    name: string;
+    qualifiedName: string;
+    filePath: string;
+    kind: NodeKind;
+    fanIn: number;
+    fanOut: number;
+    /** Why this surfaced — the threshold it breached (REQ-MAINT-002.A3). */
+    reason: string;
+}
+export interface OversizedFinding {
+    nodeId: string;
+    name: string;
+    qualifiedName: string;
+    filePath: string;
+    kind: NodeKind;
+    startLine: number;
+    endLine: number;
+    lines: number;
+    reason: string;
+}
+export interface GodFileFinding {
+    filePath: string;
+    symbolCount: number;
+    reason: string;
+}
+export interface CycleFinding {
+    /** Files forming a dependency cycle (sorted). */
+    files: string[];
+    reason: string;
+}
+export interface DeadCodeFinding {
+    nodeId: string;
+    name: string;
+    qualifiedName: string;
+    filePath: string;
+    kind: NodeKind;
+    startLine: number;
+    reason: string;
+}
+export interface MaintainabilityReport {
+    thresholds: MaintainabilityThresholds;
+    coupling: CouplingFinding[];
+    oversized: OversizedFinding[];
+    godFiles: GodFileFinding[];
+    cycles: CycleFinding[];
+    deadCode: DeadCodeFinding[];
+    /** True when nothing crossed a threshold — an explicit clean result, not empty/ambiguous. */
+    clean: boolean;
+}
+/**
+ * Compute the maintainability report from the graph. Pure read — never writes.
+ */
+export declare function computeMaintainability(queries: QueryBuilder, thresholds?: MaintainabilityThresholds, exclude?: string[]): MaintainabilityReport;
+/** Default name of the checked-in project config file at the project root. */
+export declare const CONFIG_FILE_NAME = "specship.config.json";
+/**
+ * Resolve effective thresholds (REQ-MAINT-002): defaults < checked-in
+ * `specship.config.json` (`maintainability.thresholds`) < explicit override.
+ * A missing or unparseable config silently falls back to defaults.
+ */
+export declare function resolveThresholds(projectRoot: string, override?: Partial<MaintainabilityThresholds>): MaintainabilityThresholds;
+/**
+ * Resolve the exclude globs: the built-in DEFAULT_EXCLUDE plus any
+ * `maintainability.exclude` array from specship.config.json (additive — config
+ * extends the defaults rather than replacing them).
+ */
+export declare function resolveExclude(projectRoot: string): string[];
+//# sourceMappingURL=maintainability.d.ts.map

package/dist/graph/maintainability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintainability.d.ts","sourceRoot":"","sources":["../../src/graph/maintainability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAc,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEhD,6FAA6F;AAC7F,MAAM,WAAW,yBAAyB;IACxC,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,gBAAgB,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,kBAAkB,EAAE,yBAIhC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,EASnC,CAAC;AAoBF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,yBAAyB,CAAC;IACtC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,6FAA6F;IAC7F,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,YAAY,EACrB,UAAU,GAAE,yBAA8C,EAC1D,OAAO,GAAE,MAAM,EAAoB,GAClC,qBAAqB,CAyFvB;AAgDD,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,yBAAyB,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC,GAC5C,yBAAyB,CAe3B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAW5D"}