waymark-engine 1.0.0

package/dist/src/paths.js

@@ -0,0 +1,134 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { TextDecoder } from "node:util";
+import { WaymarkError } from "./types.js";
+const decoder = new TextDecoder("utf-8", { fatal: true });
+export function sha256(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}
+/**
+ * Resolve the repository root: `git rev-parse --show-toplevel` when inside a Git
+ * worktree, otherwise the process cwd. The discovery engine itself needs no Git —
+ * the fallback keeps the CLI and library usable outside a repository.
+ */
+export function repoRoot(cwd = process.cwd()) {
+    try {
+        const output = execFileSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
+            encoding: "buffer",
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+            timeout: 5000,
+        });
+        const root = decoder.decode(output).trim();
+        if (!root)
+            throw new Error("empty Git root");
+        return fs.realpathSync.native(root);
+    }
+    catch {
+        return fs.realpathSync.native(cwd);
+    }
+}
+function isInside(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+export function normalizeRelativePath(input) {
+    if (typeof input !== "string" || input.length === 0 || input.includes("\0")) {
+        throw new WaymarkError("INVALID_PATH", "Path must be a nonempty repository-relative path");
+    }
+    const slashPath = input.replaceAll("\\", "/");
+    if (path.posix.isAbsolute(slashPath) || /^[A-Za-z]:/u.test(slashPath)) {
+        throw new WaymarkError("INVALID_PATH", "Absolute paths are not allowed");
+    }
+    const normalized = path.posix.normalize(slashPath);
+    if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+        throw new WaymarkError("INVALID_PATH", "Path traversal is not allowed");
+    }
+    return normalized.replace(/^\.\//u, "");
+}
+export function resolveRepositoryFile(root, storedPath) {
+    const relative = normalizeRelativePath(storedPath);
+    const lexical = path.resolve(root, ...relative.split("/"));
+    if (!isInside(root, lexical))
+        throw new WaymarkError("INVALID_PATH", "Path escapes repository root");
+    let real;
+    try {
+        real = fs.realpathSync.native(lexical);
+    }
+    catch {
+        throw new WaymarkError("FILE_MISSING", `Referenced file is missing: ${relative}`, 2);
+    }
+    const realRoot = fs.realpathSync.native(root);
+    if (!isInside(realRoot, real))
+        throw new WaymarkError("SYMLINK_ESCAPE", "Referenced symlink escapes repository root", 2);
+    const stat = fs.statSync(real);
+    if (!stat.isFile())
+        throw new WaymarkError("NOT_REGULAR_FILE", `Referenced path is not a regular file: ${relative}`, 2);
+    return { lexical, real };
+}
+export function readFileBytes(root, storedPath) {
+    const file = resolveRepositoryFile(root, storedPath);
+    return { path: file.real, bytes: fs.readFileSync(file.real) };
+}
+export function readFileText(root, storedPath) {
+    const result = readFileBytes(root, storedPath);
+    try {
+        return { ...result, text: decoder.decode(result.bytes) };
+    }
+    catch {
+        throw new WaymarkError("INVALID_UTF8", `Referenced file is not valid UTF-8: ${storedPath}`, 2);
+    }
+}
+export function normalizedLines(text) {
+    return text.replace(/\r\n?/gu, "\n").split("\n");
+}
+export function extractRange(lines, range) {
+    if (!Number.isInteger(range.start) || !Number.isInteger(range.end) || range.start < 1 || range.end < range.start || range.end > lines.length) {
+        throw new WaymarkError("INVALID_RANGE", `Invalid line range ${range.start}-${range.end}`);
+    }
+    return lines.slice(range.start - 1, range.end).join("\n");
+}
+export function normalizeSpan(text) {
+    const nfc = text.normalize("NFC").replace(/\r\n?/gu, "\n");
+    const lines = nfc.split("\n").map((line) => line.replace(/[ \t]+$/u, ""));
+    while (lines.length > 0 && lines[0]?.trim() === "")
+        lines.shift();
+    while (lines.length > 0 && lines[lines.length - 1]?.trim() === "")
+        lines.pop();
+    return lines.join("\n");
+}
+function tokens(line) {
+    return line.match(/[\p{L}\p{N}_]+/gu) ?? [];
+}
+export function structuralSignature(normalized) {
+    const lines = normalized.split("\n");
+    const first = lines.find((line) => line.trim() !== "") ?? "";
+    const last = [...lines].reverse().find((line) => line.trim() !== "") ?? "";
+    return {
+        firstHash: sha256(first),
+        lastHash: sha256(last),
+        firstTokensPrefix: tokens(first).slice(0, 10),
+        lastTokensPrefix: tokens(last).slice(0, 10),
+    };
+}
+/**
+ * Anchor a repository-relative file range: full-file hash plus a normalized,
+ * relocation-tolerant span hash. This is the tamper-evidence primitive — the
+ * same one the in-flight continuity ledger used, kept standalone because it is
+ * the cheapest way to pin "this span said X" to a later integrity check.
+ */
+export function anchorForRange(root, storedPath, range) {
+    const file = readFileText(root, storedPath);
+    const lines = normalizedLines(file.text);
+    const normalized = normalizeSpan(extractRange(lines, range));
+    return {
+        fileSha256: sha256(file.bytes),
+        normalizedSpanHash: sha256(Buffer.from(normalized, "utf8")),
+        normalizedSpanLen: Buffer.byteLength(normalized, "utf8"),
+        spanLineCount: range.end - range.start + 1,
+        structuralSignature: structuralSignature(normalized),
+    };
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/paths.js.map

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

package/dist/src/types.d.ts

@@ -0,0 +1,44 @@
+export type AdapterProfile = "capn-cli" | "none";
+export type VerificationStatus = "FRESH" | "MOVED" | "STALE";
+export interface LineRange {
+    start: number;
+    end: number;
+}
+export interface StructuralSignature {
+    firstHash: string;
+    lastHash: string;
+    firstTokensPrefix: string[];
+    lastTokensPrefix: string[];
+}
+export interface HopRecord {
+    index: number;
+    path: string;
+    label: string;
+    inference: string;
+    range: LineRange;
+    fileSha256: string;
+    normalizedSpanHash: string;
+    normalizedSpanLen: number;
+    spanLineCount: number;
+    structuralSignature: StructuralSignature;
+}
+export interface HopCheck {
+    index: number;
+    path: string;
+    status: VerificationStatus;
+    originalRange: LineRange;
+    resolvedRange?: LineRange;
+    reason?: string;
+    currentFileSha256?: string;
+}
+export interface PublicationResult {
+    published: boolean;
+    adapter: AdapterProfile;
+    output: string;
+    error?: string;
+}
+export declare class WaymarkError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    constructor(code: string, message: string, exitCode?: number);
+}

package/dist/src/types.js

@@ -0,0 +1,11 @@
+export class WaymarkError extends Error {
+    code;
+    exitCode;
+    constructor(code, message, exitCode = 1) {
+        super(message);
+        this.name = "WaymarkError";
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AA8CA,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAS;IACb,QAAQ,CAAS;IAE1B,YAAY,IAAY,EAAE,OAAe,EAAE,QAAQ,GAAG,CAAC;QACrD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "waymark-engine",
+  "version": "1.0.0",
+  "description": "Waymark Engine: two-phase symbolic+semantic discovery (Tree-sitter WASM AST + Capn FTS5) for AI coding agents — clean misses instead of guesses.",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./cli": "./dist/src/cli.js"
+  },
+  "bin": {
+    "waymark": "./dist/src/cli.js",
+    "waymark-ask": "./bin/waymark-ask.mjs",
+    "waymark-discover": "./bin/waymark-discover.mjs",
+    "waymark-chart": "./bin/waymark-chart.mjs",
+    "waymark-mcp": "./dist/src/mcp/capnIndex.js"
+  },
+  "files": [
+    "dist/src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paragon-ux/waymark-engine.git"
+  },
+  "keywords": [
+    "agent",
+    "ast",
+    "tree-sitter",
+    "discovery",
+    "code-search",
+    "mcp",
+    "semantic-search",
+    "symbols",
+    "llm-tools"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test \"dist/test/**/*.test.js\"",
+    "verify": "npm run build && node --test \"dist/test/**/*.test.js\"",
+    "prepublishOnly": "npm run verify"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "capn-hook": "0.2.2",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "tree-sitter-wasms": "^0.1.13",
+    "web-tree-sitter": "0.24.0"
+  }
+}