@specship/specship 0.11.0

package/dist/graph/maintainability.js

@@ -0,0 +1,299 @@
+"use strict";
+/**
+ * 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).
+ */
+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.CONFIG_FILE_NAME = exports.LOW_CONFIDENCE_CLASSES = exports.HIGH_PRECISION_CLASSES = exports.DEFAULT_EXCLUDE = exports.DEFAULT_THRESHOLDS = void 0;
+exports.computeMaintainability = computeMaintainability;
+exports.highPrecisionClean = highPrecisionClean;
+exports.resolveThresholds = resolveThresholds;
+exports.resolveExclude = resolveExclude;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const picomatch_1 = __importDefault(require("picomatch"));
+exports.DEFAULT_THRESHOLDS = {
+    highDegree: 20,
+    largeSymbolLines: 200,
+    godFileSymbols: 40,
+};
+/**
+ * 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.
+ */
+exports.DEFAULT_EXCLUDE = [
+    '**/*.d.ts',
+    '**/*.min.js',
+    '**/*.map',
+    '**/dist/**',
+    '**/build/**',
+    '**/vendor/**',
+    '**/public/web/**',
+    '**/chunk-*.js',
+];
+/** Definable code symbols considered by the size / coupling / dead-code signals. */
+const SYMBOL_KINDS = new Set([
+    'function', 'method', 'class', 'struct', 'interface', 'trait', 'protocol', 'enum', 'type_alias',
+]);
+/**
+ * Edge kinds that represent a *use* / dependency (so they count toward coupling
+ * and reachability). `contains` (structural parent→child) and `exports` are not
+ * uses. Heuristic-provenance `calls`/`references` edges ARE uses — which is why a
+ * symbol reached only via a synthesized dynamic-dispatch edge is never flagged
+ * dead (REQ-MAINT-001.A4).
+ */
+function isUseEdge(kind) {
+    return kind !== 'contains' && kind !== 'exports';
+}
+const TEST_FILE = /(^|\/)(__tests__|tests?|spec)\/|\.(test|spec|_test)\.|_test\.[a-z]+$|\.test\.[a-z]+$|\.spec\.[a-z]+$/i;
+/**
+ * Compute the maintainability report from the graph. Pure read — never writes.
+ */
+function computeMaintainability(queries, thresholds = exports.DEFAULT_THRESHOLDS, exclude = exports.DEFAULT_EXCLUDE) {
+    // Scope analysis to source files — drop generated/vendored ones up front so
+    // they never appear as findings and never inflate a kept node's degree.
+    const isExcluded = exclude.length
+        ? (0, picomatch_1.default)(exclude, { dot: true })
+        : () => false;
+    const nodes = queries.getAllNodes().filter((n) => !isExcluded(n.filePath));
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const fanIn = new Map();
+    const fanOut = new Map();
+    // file → set of files it imports (for cycle detection)
+    const fileImports = new Map();
+    for (const n of nodes) {
+        const out = queries.getOutgoingEdges(n.id);
+        for (const e of out) {
+            if (!byId.has(e.target))
+                continue; // edge to an excluded/missing node — ignore
+            if (isUseEdge(e.kind)) {
+                fanOut.set(e.source, (fanOut.get(e.source) ?? 0) + 1);
+                fanIn.set(e.target, (fanIn.get(e.target) ?? 0) + 1);
+            }
+            if (e.kind === 'imports') {
+                const srcFile = n.filePath;
+                const tgtFile = byId.get(e.target)?.filePath;
+                if (srcFile && tgtFile && srcFile !== tgtFile) {
+                    let set = fileImports.get(srcFile);
+                    if (!set) {
+                        set = new Set();
+                        fileImports.set(srcFile, set);
+                    }
+                    set.add(tgtFile);
+                }
+            }
+        }
+    }
+    // --- coupling + size + dead-code (per symbol) ---
+    const coupling = [];
+    const oversized = [];
+    const deadCode = [];
+    const symbolsPerFile = new Map();
+    for (const n of nodes) {
+        if (!SYMBOL_KINDS.has(n.kind))
+            continue;
+        symbolsPerFile.set(n.filePath, (symbolsPerFile.get(n.filePath) ?? 0) + 1);
+        const fi = fanIn.get(n.id) ?? 0;
+        const fo = fanOut.get(n.id) ?? 0;
+        if (fi >= thresholds.highDegree || fo >= thresholds.highDegree) {
+            coupling.push({
+                nodeId: n.id, name: n.name, qualifiedName: n.qualifiedName, filePath: n.filePath, kind: n.kind, fanIn: fi, fanOut: fo,
+                reason: `fan-in ${fi} / fan-out ${fo} (threshold ≥ ${thresholds.highDegree})`,
+            });
+        }
+        const lines = Math.max(0, (n.endLine ?? 0) - (n.startLine ?? 0));
+        if (lines >= thresholds.largeSymbolLines) {
+            oversized.push({
+                nodeId: n.id, name: n.name, qualifiedName: n.qualifiedName, filePath: n.filePath, kind: n.kind, startLine: n.startLine ?? 0, endLine: n.endLine ?? 0, lines,
+                reason: `${lines} lines (threshold ≥ ${thresholds.largeSymbolLines})`,
+            });
+        }
+        // dead-code: no use-edges in, not part of the public surface, not a test fixture
+        if (fi === 0 && !n.isExported && !TEST_FILE.test(n.filePath)) {
+            deadCode.push({
+                nodeId: n.id, name: n.name, qualifiedName: n.qualifiedName, filePath: n.filePath, kind: n.kind, startLine: n.startLine ?? 0,
+                reason: 'no incoming use-edges; not exported',
+            });
+        }
+    }
+    // --- god files ---
+    const godFiles = [];
+    for (const [filePath, count] of symbolsPerFile) {
+        if (count >= thresholds.godFileSymbols) {
+            godFiles.push({ filePath, symbolCount: count, reason: `${count} symbols (threshold ≥ ${thresholds.godFileSymbols})` });
+        }
+    }
+    // --- dependency cycles (Tarjan SCC over the file-import graph) ---
+    const cycles = findCycles(fileImports);
+    // deterministic ordering
+    coupling.sort((a, b) => (b.fanIn + b.fanOut) - (a.fanIn + a.fanOut) || cmp(a.nodeId, b.nodeId));
+    oversized.sort((a, b) => b.lines - a.lines || cmp(a.nodeId, b.nodeId));
+    godFiles.sort((a, b) => b.symbolCount - a.symbolCount || cmp(a.filePath, b.filePath));
+    deadCode.sort((a, b) => cmp(a.filePath, b.filePath) || a.startLine - b.startLine || cmp(a.nodeId, b.nodeId));
+    const clean = coupling.length === 0 && oversized.length === 0 && godFiles.length === 0 && cycles.length === 0 && deadCode.length === 0;
+    return { thresholds, coupling, oversized, godFiles, cycles, deadCode, clean };
+}
+function cmp(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+// =============================================================================
+// Report tiering (HEALTH-GATEWAY-DOC) — which finding classes are trustworthy
+// enough for the default human report, and which are lower-confidence opt-ins.
+// =============================================================================
+/** Finding classes shown by default — demonstrably precise (REQ-HEALTH-001). */
+exports.HIGH_PRECISION_CLASSES = ['oversized', 'godFiles', 'cycles'];
+/**
+ * Lower-confidence finding classes — hidden unless explicitly requested
+ * (REQ-HEALTH-002). Dead-code is high-volume/heuristic; coupling fan-in is
+ * inflated by method-name-collision artifacts.
+ */
+exports.LOW_CONFIDENCE_CLASSES = ['coupling', 'deadCode'];
+/**
+ * True when no high-precision finding crossed a threshold — the default gateway
+ * view is clean even if lower-confidence (dead-code/coupling) findings exist
+ * (REQ-HEALTH-001.A3).
+ */
+function highPrecisionClean(r) {
+    return r.oversized.length === 0 && r.godFiles.length === 0 && r.cycles.length === 0;
+}
+/**
+ * Tarjan's strongly-connected-components over the file-import graph. Returns
+ * every SCC of size > 1 (a genuine import cycle), each as a sorted file list,
+ * the whole list sorted for determinism.
+ */
+function findCycles(graph) {
+    let index = 0;
+    const idx = new Map();
+    const low = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    // stable node order so the SCC partition is deterministic
+    const order = [...graph.keys()].sort(cmp);
+    const strongconnect = (v) => {
+        idx.set(v, index);
+        low.set(v, index);
+        index++;
+        stack.push(v);
+        onStack.add(v);
+        const neighbors = [...(graph.get(v) ?? [])].sort(cmp);
+        for (const w of neighbors) {
+            if (!idx.has(w)) {
+                // w may be an import target with no outgoing edges — still a graph node
+                strongconnect(w);
+                low.set(v, Math.min(low.get(v), low.get(w)));
+            }
+            else if (onStack.has(w)) {
+                low.set(v, Math.min(low.get(v), idx.get(w)));
+            }
+        }
+        if (low.get(v) === idx.get(v)) {
+            const comp = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                comp.push(w);
+            } while (w !== v);
+            if (comp.length > 1)
+                sccs.push(comp.sort(cmp));
+        }
+    };
+    for (const v of order)
+        if (!idx.has(v))
+            strongconnect(v);
+    return sccs
+        .sort((a, b) => cmp(a[0] ?? '', b[0] ?? ''))
+        .map((files) => ({ files, reason: `${files.length} files form an import cycle` }));
+}
+/** Default name of the checked-in project config file at the project root. */
+exports.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.
+ */
+function resolveThresholds(projectRoot, override) {
+    let fromConfig = {};
+    try {
+        const raw = fs.readFileSync(path.join(projectRoot, exports.CONFIG_FILE_NAME), 'utf-8');
+        const cfg = JSON.parse(raw);
+        const t = cfg?.maintainability?.thresholds;
+        if (t && typeof t === 'object') {
+            for (const k of ['highDegree', 'largeSymbolLines', 'godFileSymbols']) {
+                if (typeof t[k] === 'number' && Number.isFinite(t[k]))
+                    fromConfig[k] = t[k];
+            }
+        }
+    }
+    catch {
+        // no config / unparseable → defaults
+    }
+    return { ...exports.DEFAULT_THRESHOLDS, ...fromConfig, ...(override ?? {}) };
+}
+/**
+ * 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).
+ */
+function resolveExclude(projectRoot) {
+    let extra = [];
+    try {
+        const raw = fs.readFileSync(path.join(projectRoot, exports.CONFIG_FILE_NAME), 'utf-8');
+        const cfg = JSON.parse(raw);
+        const e = cfg?.maintainability?.exclude;
+        if (Array.isArray(e))
+            extra = e.filter((x) => typeof x === 'string');
+    }
+    catch {
+        // no config / unparseable → defaults only
+    }
+    return [...exports.DEFAULT_EXCLUDE, ...extra];
+}
+//# sourceMappingURL=maintainability.js.map

package/dist/graph/maintainability.js.map

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

package/dist/graph/queries.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Graph Query Functions
+ *
+ * Higher-level query functions built on top of traversal algorithms.
+ */
+import { Node, Context, Subgraph } from '../types';
+import { QueryBuilder } from '../db/queries';
+import { GraphTraverser } from './traversal';
+/**
+ * Graph query manager for complex queries
+ */
+export declare class GraphQueryManager {
+    private queries;
+    private traverser;
+    constructor(queries: QueryBuilder);
+    /**
+     * Get full context for a node
+     *
+     * Returns the focal node along with its ancestors, children,
+     * and both incoming and outgoing references.
+     *
+     * @param nodeId - ID of the focal node
+     * @returns Context object with all related information
+     */
+    getContext(nodeId: string): Context;
+    /**
+     * Get dependencies of a file
+     *
+     * Returns all files that this file imports from.
+     *
+     * @param filePath - Path to the file
+     * @returns Array of file paths this file depends on
+     */
+    getFileDependencies(filePath: string): string[];
+    /**
+     * Get dependents of a file
+     *
+     * Returns all files that import from this file.
+     *
+     * @param filePath - Path to the file
+     * @returns Array of file paths that depend on this file
+     */
+    getFileDependents(filePath: string): string[];
+    /**
+     * Get all symbols exported by a file
+     *
+     * @param filePath - Path to the file
+     * @returns Array of exported nodes
+     */
+    getExportedSymbols(filePath: string): Node[];
+    /**
+     * Find symbols by qualified name pattern
+     *
+     * @param pattern - Pattern to match (supports * wildcard)
+     * @returns Array of matching nodes
+     */
+    findByQualifiedName(pattern: string): Node[];
+    /**
+     * Get the module/package structure
+     *
+     * Returns a tree structure of files organized by directory.
+     *
+     * @returns Map of directory paths to contained files
+     */
+    getModuleStructure(): Map<string, string[]>;
+    /**
+     * Find circular dependencies in the graph
+     *
+     * @returns Array of cycles, each cycle is an array of node IDs
+     */
+    findCircularDependencies(): string[][];
+    /**
+     * Get complexity metrics for a node
+     *
+     * @param nodeId - ID of the node
+     * @returns Object containing various complexity metrics
+     */
+    getNodeMetrics(nodeId: string): {
+        incomingEdgeCount: number;
+        outgoingEdgeCount: number;
+        callCount: number;
+        callerCount: number;
+        childCount: number;
+        depth: number;
+    };
+    /**
+     * Find dead code (nodes with no incoming references)
+     *
+     * @param kinds - Node kinds to check (default: functions, methods, classes)
+     * @returns Array of unreferenced nodes
+     */
+    findDeadCode(kinds?: Node['kind'][]): Node[];
+    /**
+     * Get subgraph containing nodes matching a filter
+     *
+     * @param filter - Filter function to select nodes
+     * @param includeEdges - Whether to include edges between matching nodes
+     * @returns Subgraph containing matching nodes
+     */
+    getFilteredSubgraph(filter: (node: Node) => boolean, includeEdges?: boolean): Subgraph;
+    /**
+     * Access the underlying traverser for direct traversal operations
+     */
+    getTraverser(): GraphTraverser;
+}
+//# sourceMappingURL=queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/graph/queries.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAQ,OAAO,EAAE,QAAQ,EAAY,MAAM,UAAU,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,SAAS,CAAiB;gBAEtB,OAAO,EAAE,YAAY;IAKjC;;;;;;;;OAQG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IA8EnC;;;;;;;OAOG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;IAqB/C;;;;;;;OAOG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;IAgC7C;;;;;OAKG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE;IAK5C;;;;;OAKG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE;IAkC5C;;;;;;OAMG;IACH,kBAAkB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAiB3C;;;;OAIG;IACH,wBAAwB,IAAI,MAAM,EAAE,EAAE;IAwCtC;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;QAC9B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;KACf;IAoBD;;;;;OAKG;IACH,YAAY,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE;IA0B5C;;;;;;OAMG;IACH,mBAAmB,CACjB,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,EAC/B,YAAY,GAAE,OAAc,GAC3B,QAAQ;IAgDX;;OAEG;IACH,YAAY,IAAI,cAAc;CAG/B"}