@mortice/mapwright 0.8.0

package/dist/queries/reuseCandidates.js

@@ -0,0 +1,181 @@
+import { nameMatchReasons } from "./ranking.js";
+export function findReuseCandidates(snapshot, options) {
+    const query = options.query.trim();
+    const normalizedQuery = query.toLowerCase();
+    const tokens = tokenize(normalizedQuery);
+    const limit = Math.max(1, options.limit ?? 10);
+    const capabilityCandidates = snapshot.capabilities
+        .filter((capability) => {
+        if (options.capabilityId && capability.id !== options.capabilityId) {
+            return false;
+        }
+        if (options.packageId && !capability.packages.includes(options.packageId)) {
+            return false;
+        }
+        return true;
+    })
+        .map((capability) => scoreCapability(snapshot, capability, normalizedQuery, tokens));
+    const publicApiCandidates = snapshot.publicApis
+        .filter((api) => {
+        if (options.capabilityId && !api.capabilityIds.includes(options.capabilityId)) {
+            return false;
+        }
+        if (!options.packageId) {
+            return true;
+        }
+        const symbol = snapshot.symbols.find((item) => item.id === api.symbolId);
+        const ownerPackage = symbol ? findOwningPackageId(snapshot, symbol.filePath) : undefined;
+        return ownerPackage === options.packageId;
+    })
+        .map((api) => scorePublicApi(snapshot, api, normalizedQuery, tokens));
+    const candidates = [...capabilityCandidates, ...publicApiCandidates]
+        .filter((candidate) => candidate.score > 0)
+        .sort((a, b) => b.score - a.score || a.kind.localeCompare(b.kind) || a.id.localeCompare(b.id))
+        .slice(0, limit);
+    return { query, tokens, candidates };
+}
+/**
+ * Thin wrapper over {@link findReuseCandidates} that annotates each candidate
+ * with closed-vocabulary match reasons derived from its name. Ordering and
+ * scoring are unchanged from the underlying reuse scorer.
+ */
+export function rankReuseCandidates(snapshot, options) {
+    const result = findReuseCandidates(snapshot, options);
+    const candidates = result.candidates.map((candidate) => {
+        const name = candidate.kind === "capability"
+            ? snapshot.capabilities.find((item) => item.id === candidate.id)?.name
+            : snapshot.publicApis.find((item) => item.id === candidate.id)?.name;
+        const reasons = name ? nameMatchReasons(name, result.query, "exact_declared_name") : [];
+        return { ...candidate, matchReasons: reasons };
+    });
+    return { query: result.query, tokens: result.tokens, candidates };
+}
+function scoreCapability(snapshot, capability, query, tokens) {
+    let score = 0;
+    const reasons = [];
+    if (query && capability.id.toLowerCase() === query) {
+        score += 100;
+        reasons.push("matched capability id");
+    }
+    if (query && capability.name.toLowerCase().includes(query)) {
+        score += 35;
+        reasons.push("matched capability name");
+    }
+    if (tokens.some((token) => capability.keywords.map((keyword) => keyword.toLowerCase()).includes(token))) {
+        score += 20;
+        reasons.push("matched capability keywords");
+    }
+    const linkedApis = snapshot.publicApis.filter((api) => capability.publicApis.includes(api.id));
+    if (query && linkedApis.some((api) => api.name.toLowerCase().includes(query))) {
+        score += 25;
+        reasons.push("matched public API name");
+    }
+    const linkedSymbols = snapshot.symbols.filter((symbol) => capability.symbols.includes(symbol.id));
+    if (query && linkedSymbols.some((symbol) => symbol.name.toLowerCase().includes(query))) {
+        score += 20;
+        reasons.push("matched symbol name");
+    }
+    const linkedPackages = snapshot.packages.filter((pkg) => capability.packages.includes(pkg.id));
+    if (query && linkedPackages.some((pkg) => pkg.name.toLowerCase().includes(query))) {
+        score += 15;
+        reasons.push("matched package name");
+    }
+    const searchableText = [
+        capability.summary ?? "",
+        capability.intendedUse ?? "",
+        ...capability.contracts,
+        ...capability.limitations,
+        ...capability.tests,
+        ...capability.examples
+    ].join(" ").toLowerCase();
+    if (query && searchableText.includes(query)) {
+        score += 12;
+        reasons.push("matched capability documentation");
+    }
+    if (score > 0
+        && (capability.tests.length > 0 || linkedApis.some((api) => api.tests.length > 0))
+        && (capability.examples.length > 0 || linkedApis.some((api) => api.examples.length > 0))) {
+        score += 6;
+        reasons.push("has tests and examples");
+    }
+    return {
+        kind: "capability",
+        id: capability.id,
+        score: normalizeScore(score, 200),
+        reasons: dedupe(reasons)
+    };
+}
+function scorePublicApi(snapshot, api, query, tokens) {
+    let score = 0;
+    const reasons = [];
+    if (query && api.id.toLowerCase() === query) {
+        score += 100;
+        reasons.push("matched public API id");
+    }
+    if (query && api.name.toLowerCase().includes(query)) {
+        score += 45;
+        reasons.push("matched public API name");
+    }
+    if (tokens.some((token) => api.capabilityIds.some((capabilityId) => capabilityId.toLowerCase().includes(token)))) {
+        score += 20;
+        reasons.push("matched linked capability");
+    }
+    const symbol = snapshot.symbols.find((item) => item.id === api.symbolId);
+    if (query && symbol?.name.toLowerCase().includes(query)) {
+        score += 20;
+        reasons.push("matched implementation symbol");
+    }
+    if (query) {
+        const owningPackageId = symbol ? findOwningPackageId(snapshot, symbol.filePath) : undefined;
+        const owningPackage = owningPackageId ? snapshot.packages.find((pkg) => pkg.id === owningPackageId) : undefined;
+        if (owningPackage?.name.toLowerCase().includes(query)) {
+            score += 15;
+            reasons.push("matched owning package");
+        }
+    }
+    const searchableText = [
+        api.intendedUse ?? "",
+        api.inputs ?? "",
+        api.returns ?? "",
+        ...api.contracts,
+        ...api.tests,
+        ...api.examples
+    ].join(" ").toLowerCase();
+    if (query && searchableText.includes(query)) {
+        score += 12;
+        reasons.push("matched API documentation");
+    }
+    if (score > 0 && api.tests.length > 0 && api.examples.length > 0) {
+        score += 6;
+        reasons.push("has tests and examples");
+    }
+    return {
+        kind: "publicApi",
+        id: api.id,
+        score: normalizeScore(score, 200),
+        reasons: dedupe(reasons)
+    };
+}
+function findOwningPackageId(snapshot, filePath) {
+    const candidates = snapshot.packages
+        .filter((pkg) => pkg.path === "." || filePath === pkg.path || filePath.startsWith(`${pkg.path}/`))
+        .sort((a, b) => b.path.length - a.path.length || a.id.localeCompare(b.id));
+    return candidates[0]?.id;
+}
+function tokenize(input) {
+    return input
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter(Boolean)
+        .sort();
+}
+function normalizeScore(score, max) {
+    if (score <= 0) {
+        return 0;
+    }
+    const normalized = Math.min(1, score / max);
+    return Number(normalized.toFixed(4));
+}
+function dedupe(values) {
+    return [...new Set(values)].sort();
+}

package/dist/queries/symbols.d.ts

@@ -0,0 +1,40 @@
+import type { CatalogueSnapshot, SymbolRecord } from "../catalogue/schema.js";
+import { type RankedEnvelope } from "./ranking.js";
+import { type EditingContext } from "./editingContext.js";
+export interface SearchSymbolsOptions {
+    query: string;
+    kind?: SymbolRecord["kind"];
+    language?: string;
+    packageId?: string;
+    publicOnly?: boolean;
+    capabilityId?: string;
+    hasExamples?: boolean;
+    hasTests?: boolean;
+    limit?: number;
+    offset?: number;
+}
+export interface SymbolCompact {
+    id: string;
+    name: string;
+    qualifiedName: string;
+    kind: SymbolRecord["kind"];
+    language: string;
+    filePath: string;
+    packageId?: string;
+    visibility: SymbolRecord["visibility"];
+    exported: boolean;
+}
+export declare function toSymbolCompact(symbol: SymbolRecord): SymbolCompact;
+export declare function searchSymbols(snapshot: CatalogueSnapshot, options: SearchSymbolsOptions): RankedEnvelope<SymbolCompact>;
+export interface GetSymbolContextOptions {
+    /** Opt-in bounded editing context (Gate 4). Default false. */
+    includeEditingContext?: boolean;
+    /** Per-section budget for editing context when included. */
+    editingContextLimit?: number;
+}
+export interface SymbolContextResult {
+    symbol: SymbolRecord;
+    /** Bounded, advisory editing context; present only when opted in. */
+    editingContext?: EditingContext;
+}
+export declare function getSymbolContext(snapshot: CatalogueSnapshot, symbolId: string, options?: GetSymbolContextOptions): SymbolContextResult | undefined;

package/dist/queries/symbols.js

@@ -0,0 +1,41 @@
+import { buildRankedEnvelope, rankSymbols } from "./ranking.js";
+import { buildEditingContext } from "./editingContext.js";
+export function toSymbolCompact(symbol) {
+    return {
+        id: symbol.id,
+        name: symbol.name,
+        qualifiedName: symbol.qualifiedName,
+        kind: symbol.kind,
+        language: symbol.language,
+        filePath: symbol.filePath,
+        packageId: symbol.packageId,
+        visibility: symbol.visibility,
+        exported: symbol.exported
+    };
+}
+export function searchSymbols(snapshot, options) {
+    const filters = {
+        kind: options.kind,
+        language: options.language,
+        packageId: options.packageId,
+        publicOnly: options.publicOnly,
+        capabilityId: options.capabilityId,
+        hasExamples: options.hasExamples,
+        hasTests: options.hasTests
+    };
+    const ranked = rankSymbols(options.query, snapshot.symbols, filters, snapshot);
+    return buildRankedEnvelope(options.query, ranked, toSymbolCompact, filters, {
+        offset: options.offset,
+        limit: options.limit
+    });
+}
+export function getSymbolContext(snapshot, symbolId, options = {}) {
+    const symbol = snapshot.symbols.find((item) => item.id === symbolId);
+    if (!symbol) {
+        return undefined;
+    }
+    const editingContext = options.includeEditingContext
+        ? buildEditingContext(snapshot, { symbol }, { perSectionLimit: options.editingContextLimit })
+        : undefined;
+    return { symbol, editingContext };
+}

package/dist/security/pathPolicy.d.ts

@@ -0,0 +1,12 @@
+export declare function toWorkspaceRelative(workspaceRoot: string, targetPath: string): string;
+export declare function isWithinWorkspace(workspaceRoot: string, targetPath: string): boolean;
+/**
+ * Resolve a filesystem path to its canonical target.
+ * Returns undefined on missing paths, broken symlinks, or inaccessible targets.
+ */
+export declare function resolveCanonicalPath(input: string): string | undefined;
+/**
+ * True when candidatePath's canonical target is inside workspaceRoot's canonical root.
+ * False when either path cannot be canonicalised or the target escapes the root.
+ */
+export declare function isCanonicalWithinWorkspace(workspaceRoot: string, candidatePath: string): boolean;

package/dist/security/pathPolicy.js

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { realpathSync } from "node:fs";
+export function toWorkspaceRelative(workspaceRoot, targetPath) {
+    const relative = path.relative(path.resolve(workspaceRoot), path.resolve(targetPath));
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        return "";
+    }
+    return relative.replaceAll("\\", "/");
+}
+export function isWithinWorkspace(workspaceRoot, targetPath) {
+    const resolvedRoot = path.resolve(workspaceRoot);
+    const resolvedTarget = path.resolve(targetPath);
+    return isRelativeWithinRoot(resolvedRoot, resolvedTarget);
+}
+/**
+ * Resolve a filesystem path to its canonical target.
+ * Returns undefined on missing paths, broken symlinks, or inaccessible targets.
+ */
+export function resolveCanonicalPath(input) {
+    try {
+        const realpathNative = realpathSync.native;
+        if (typeof realpathNative === "function") {
+            return realpathNative(input);
+        }
+        return realpathSync(input);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True when candidatePath's canonical target is inside workspaceRoot's canonical root.
+ * False when either path cannot be canonicalised or the target escapes the root.
+ */
+export function isCanonicalWithinWorkspace(workspaceRoot, candidatePath) {
+    const canonicalRoot = resolveCanonicalPath(workspaceRoot);
+    const canonicalTarget = resolveCanonicalPath(candidatePath);
+    if (!canonicalRoot || !canonicalTarget) {
+        return false;
+    }
+    return isRelativeWithinRoot(canonicalRoot, canonicalTarget);
+}
+function isRelativeWithinRoot(root, target) {
+    const relative = path.relative(root, target);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}

package/dist/security/secretPatterns.d.ts

@@ -0,0 +1 @@
+export declare function isSecretLikeFile(filePath: string): boolean;

package/dist/security/secretPatterns.js

@@ -0,0 +1,4 @@
+const SECRET_FILE_PATTERNS = [/^\.env(\..+)?$/i, /\.pem$/i, /\.key$/i, /\.p12$/i, /\.pfx$/i];
+export function isSecretLikeFile(filePath) {
+    return SECRET_FILE_PATTERNS.some((pattern) => pattern.test(filePath));
+}

package/dist/security/sourceAccess.d.ts

@@ -0,0 +1,12 @@
+export interface SourceAccessOptions {
+    workspaceRoot: string;
+    relativePath: string;
+    includeSource?: boolean;
+    maxSourceLines: number;
+    maxFileSizeBytes: number;
+}
+export declare function getBoundedSourcePreview(options: SourceAccessOptions): {
+    allowed: boolean;
+    reason?: string;
+    source?: string;
+};

package/dist/security/sourceAccess.js

@@ -0,0 +1,35 @@
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { isSecretLikeFile } from "./secretPatterns.js";
+import { isCanonicalWithinWorkspace, isWithinWorkspace, resolveCanonicalPath } from "./pathPolicy.js";
+export function getBoundedSourcePreview(options) {
+    if (!options.includeSource) {
+        return { allowed: false, reason: "source_disabled" };
+    }
+    if (isSecretLikeFile(path.basename(options.relativePath))) {
+        return { allowed: false, reason: "raw_source_excluded" };
+    }
+    const absolute = path.resolve(options.workspaceRoot, options.relativePath);
+    if (!isWithinWorkspace(options.workspaceRoot, absolute)) {
+        return { allowed: false, reason: "path_outside_workspace" };
+    }
+    const canonicalRoot = resolveCanonicalPath(options.workspaceRoot);
+    const canonicalTarget = resolveCanonicalPath(absolute);
+    if (!canonicalRoot || !canonicalTarget) {
+        // Missing path, broken symlink, or inaccessible target — fail closed without throwing.
+        return { allowed: false, reason: "source_missing" };
+    }
+    if (!isCanonicalWithinWorkspace(options.workspaceRoot, absolute)) {
+        return { allowed: false, reason: "path_outside_workspace" };
+    }
+    const buffer = readFileSync(canonicalTarget);
+    if (buffer.includes(0)) {
+        return { allowed: false, reason: "binary_source_excluded" };
+    }
+    const content = buffer.toString("utf8");
+    if (Buffer.byteLength(content, "utf8") > options.maxFileSizeBytes) {
+        return { allowed: false, reason: "raw_source_excluded" };
+    }
+    const lines = content.split(/\r?\n/).slice(0, options.maxSourceLines);
+    return { allowed: true, source: lines.join("\n") };
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@mortice/mapwright",
+  "version": "0.8.0",
+  "description": "Mortice Mapwright — a deterministic map of what a repository contains, what changed, and what it affects",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mapwright": "dist/cli/index.js",
+    "mapwright-mcp": "dist/mcp/server.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"import('node:fs').then(fs=>fs.rmSync('dist',{recursive:true,force:true}))\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "cli": "tsx src/cli/index.ts",
+    "mcp": "tsx src/mcp/server.ts"
+  },
+  "keywords": [
+    "mcp",
+    "mapwright",
+    "mortice",
+    "catalogue",
+    "change-intelligence"
+  ],
+  "author": "",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrewmuir/Mapwright.git"
+  },
+  "homepage": "https://github.com/andrewmuir/Mapwright#readme",
+  "bugs": {
+    "url": "https://github.com/andrewmuir/Mapwright/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "fast-glob": "^3.3.3",
+    "ignore": "^7.0.5",
+    "minimatch": "^10.2.5",
+    "typescript": "^6.0.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "tsx": "^4.23.0",
+    "vitest": "^4.1.9"
+  }
+}