@descent-vtt/spec-guard 0.5.1 → 0.7.0

package/dist/layers.js

@@ -0,0 +1,102 @@
+/**
+ * The layering rule behind `@assert-layers`.
+ *
+ * Pure, and built on almost nothing new. A layer is a pattern in the language
+ * `module=` and `exclude` already speak; a file belongs to a layer when its path
+ * matches, and a reference points into one when any name it can denote does -
+ * see `referenceForms`. That is why layering needs no resolver and works in
+ * every language spec-guard reads: it never asks which file a reference *is*,
+ * only which areas it could be about.
+ *
+ * Cycles are the opposite case, and live in `graph.ts` - see ADR-0011.
+ */
+import { createExcludeMatcher } from './glob.js';
+import { candidates, isGraphFile } from './graph.js';
+import { resolveModule } from './imports.js';
+import { languageFor } from './polyglot.js';
+/**
+ * Every name a reference can be matched under.
+ *
+ * The specifier as written and the module it resolves to, as `module=` tries -
+ * and, for the two languages whose modules are files, the files that module can
+ * denote. Without the last, a layer that names a file could never be reached:
+ * `src/runner.ts` is where the file is, `./runner.js` is what imports it, and
+ * the first rule this project wrote with file-sized layers passed while its
+ * order was reversed, because no reference matched any layer at all.
+ *
+ * Names only. Nothing here asks whether a candidate exists, which is why a layer
+ * outside the assertion's target still works: `../infrastructure/db.js` reaches
+ * `src/infrastructure/db.ts` whether or not the walk ever went there.
+ */
+export function referenceForms(specifier, importingFile) {
+    const module = resolveModule(specifier, importingFile);
+    if (isGraphFile(importingFile))
+        return [specifier, ...candidates(module)];
+    if (languageFor(importingFile) === 'python')
+        return [specifier, module, `${module}.py`, `${module}/__init__.py`];
+    return [specifier, module];
+}
+/** A function from a path to the indices of every layer that matches it. */
+export function layerMatcher(order) {
+    const matchers = order.map((pattern) => createExcludeMatcher([pattern]));
+    return (relativePath) => matchers.flatMap((matches, layer) => (matches(relativePath) ? [layer] : []));
+}
+/**
+ * Checks each file's references against the order.
+ *
+ * A file may import from its own layer and from layers listed before it. The
+ * unit of violation is the file, as it is for every import assertion: one
+ * import statement split into two is not twice the problem.
+ *
+ * A file two layers claim is not checked for violations - which layer's rule
+ * applies is exactly the thing that is unknown - and is reported instead. So is
+ * every file no layer claims, because a shared utility and a directory someone
+ * forgot to assign look identical from here and only the author can say which a
+ * count describes.
+ */
+export function checkLayers(inputs, order, includeTypes) {
+    const layersOf = layerMatcher(order);
+    // Every file in a directory imports the same few modules, and each reference
+    // is matched under some twenty names, so the same name is matched against the
+    // same patterns thousands of times on a large tree. The answer depends on the
+    // name alone. Measured on 6,977 files of node_modules: see ADR-0011.
+    const seen = new Map();
+    const reachedBy = (name) => {
+        let layers = seen.get(name);
+        if (layers === undefined) {
+            layers = layersOf(name);
+            seen.set(name, layers);
+        }
+        return layers;
+    };
+    const members = order.map(() => 0);
+    const unassigned = [];
+    const ambiguous = [];
+    const violations = [];
+    for (const { file, references } of inputs) {
+        const own = layersOf(file);
+        for (const layer of own)
+            members[layer] = members[layer] + 1;
+        if (own.length === 0) {
+            unassigned.push(file);
+            continue;
+        }
+        if (own.length > 1) {
+            ambiguous.push({ file, layers: own });
+            continue;
+        }
+        const from = own[0];
+        for (const reference of references) {
+            if (reference.typeOnly && !includeTypes)
+                continue;
+            const reached = referenceForms(reference.specifier, file).flatMap(reachedBy);
+            const to = Math.max(from, ...reached);
+            if (to > from) {
+                violations.push({ file, from, to, reference });
+                break;
+            }
+        }
+    }
+    return { members, unassigned, ambiguous, violations };
+}
+//# sourceMappingURL=layers.js.map

package/dist/layers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layers.js","sourceRoot":"","sources":["../src/layers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,aAAa,EAAwB,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,aAAqB;IACrE,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACvD,IAAI,WAAW,CAAC,aAAa,CAAC;QAAE,OAAO,CAAC,SAAS,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1E,IAAI,WAAW,CAAC,aAAa,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,KAAK,EAAE,GAAG,MAAM,cAAc,CAAC,CAAC;IACjH,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAC7B,CAAC;AA6BD,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAC,KAAwB;IACnD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,oBAAoB,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,CAAC,YAAY,EAAE,EAAE,CACtB,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,MAA6B,EAAE,KAAwB,EAAE,YAAqB;IACxG,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACrC,6EAA6E;IAC7E,8EAA8E;IAC9E,8EAA8E;IAC9E,qEAAqE;IACrE,MAAM,IAAI,GAAG,IAAI,GAAG,EAA6B,CAAC;IAClD,MAAM,SAAS,GAAG,CAAC,IAAY,EAAqB,EAAE;QACpD,IAAI,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YACxB,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,MAAM,SAAS,GAA6B,EAAE,CAAC;IAC/C,MAAM,UAAU,GAAqB,EAAE,CAAC;IAExC,KAAK,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,MAAM,EAAE,CAAC;QAC1C,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,MAAM,KAAK,IAAI,GAAG;YAAE,OAAO,CAAC,KAAK,CAAC,GAAI,OAAO,CAAC,KAAK,CAAY,GAAG,CAAC,CAAC;QACzE,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtB,SAAS;QACX,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnB,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;YACtC,SAAS;QACX,CAAC;QAED,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAW,CAAC;QAC9B,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,SAAS,CAAC,QAAQ,IAAI,CAAC,YAAY;gBAAE,SAAS;YAClD,MAAM,OAAO,GAAG,cAAc,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAC7E,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,OAAO,CAAC,CAAC;YACtC,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;gBACd,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;gBAC/C,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;AACxD,CAAC"}

package/dist/mcp.d.ts

@@ -0,0 +1,117 @@
+/**
+ * `spec-guard mcp`: the rules, served to an agent over the Model Context
+ * Protocol on stdio.
+ *
+ * No SDK. MCP over stdio is JSON-RPC 2.0, one message per line, and what a
+ * server has to get right fits in this file: framing, the two eras of the
+ * protocol, and four methods' worth of results. The official SDK brings a
+ * schema library and a dependency tree to do the same, and spec-guard's first
+ * invariant is that it has no runtime dependencies at all. ADR-0012 has the
+ * rest, including what this file deliberately does not implement.
+ *
+ * Two eras, served side by side. Revisions up to 2025-11-25 open with an
+ * `initialize` handshake; 2026-07-28 has none, and every request carries its
+ * protocol version in `_meta`. Clients of both are in use, so each request is
+ * classified on its own - by the rule the TypeScript SDK's server applies, not
+ * by one invented here: a request that claims a version in `_meta` is modern
+ * and its claim is validated; anything else, `initialize` included, is legacy.
+ */
+import type { Readable } from 'node:stream';
+import { type RunOptions } from './runner.js';
+/** Revisions that carry their version on every request. Newest first. */
+export declare const MODERN_PROTOCOL_VERSIONS: readonly string[];
+/** Revisions negotiated by `initialize`, newest first - the SDK's own list. */
+export declare const LEGACY_PROTOCOL_VERSIONS: readonly string[];
+export declare const PROTOCOL_VERSION_KEY = "io.modelcontextprotocol/protocolVersion";
+export declare const CLIENT_CAPABILITIES_KEY = "io.modelcontextprotocol/clientCapabilities";
+export declare const CLIENT_INFO_KEY = "io.modelcontextprotocol/clientInfo";
+export declare const SERVER_INFO_KEY = "io.modelcontextprotocol/serverInfo";
+export declare const PARSE_ERROR = -32700;
+export declare const INVALID_REQUEST = -32600;
+export declare const METHOD_NOT_FOUND = -32601;
+export declare const INVALID_PARAMS = -32602;
+export declare const INTERNAL_ERROR = -32603;
+/** Resource not found before 2026-07-28, which forbids it in favour of -32602. */
+export declare const LEGACY_RESOURCE_NOT_FOUND = -32002;
+export declare const UNSUPPORTED_PROTOCOL_VERSION = -32022;
+export type RequestId = string | number;
+export type Era = 'legacy' | 'modern';
+export interface ErrorObject {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+/** Everything this server ever writes. It never sends a request. */
+export type OutgoingMessage = {
+    jsonrpc: '2.0';
+    id: RequestId;
+    result: Record<string, unknown>;
+} | {
+    jsonrpc: '2.0';
+    id?: RequestId;
+    error: ErrorObject;
+};
+type JsonObject = Record<string, unknown>;
+/**
+ * What is wrong with a request's `_meta`, once it claims a protocol version.
+ *
+ * Only what the server depends on or the revision requires: a version that is a
+ * string, capabilities that are an object, and client info shaped as client info
+ * when it is sent. A claim is never silently ignored - a malformed one is an
+ * error, not a reason to fall back to legacy handling.
+ */
+export declare function envelopeIssue(meta: JsonObject): string | undefined;
+/**
+ * The era a request belongs to, or the error that answers it instead.
+ *
+ * `initialize` is the legacy handshake unless it carries a valid modern claim.
+ * Any other request is modern exactly when `_meta` holds the version key - its
+ * presence is the claim, whatever its value - and legacy otherwise.
+ */
+export declare function classifyRequest(method: string, params: JsonObject | undefined): Era;
+/** The version `initialize` settles on: the one asked for, or the newest legacy one. */
+export declare function negotiateLegacyVersion(requested: unknown): string;
+export declare const SERVER_NAME = "spec-guard";
+export declare const INSTRUCTIONS: string;
+export declare const TOOLS: readonly JsonObject[];
+export declare const RULES_URI = "spec://rules";
+export declare const DOCUMENT_URI_PREFIX = "spec://doc/";
+export declare const RESOURCE_TEMPLATES: readonly JsonObject[];
+export declare function documentUri(relativeFile: string): string;
+/** The spec path a document URI names, or null for anything else. */
+export declare function documentPath(uri: string): string | null;
+export interface McpServerOptions {
+    /** Absolute project root. */
+    root: string;
+    /** Spec globs, as on the command line. */
+    patterns: readonly string[];
+    /** Reported as the server's version. */
+    version: string;
+    /**
+     * Run settings, as the CLI flags set them. `ignoreStatus` also makes
+     * `get_architectural_rules` list rules from documents not in force by default.
+     */
+    run?: Omit<RunOptions, 'patterns' | 'root' | 'select'>;
+    /** Reads a spec document. Injected so an unreadable one can be tested. */
+    readFile?: (file: string) => Promise<string>;
+}
+/**
+ * Builds the function that answers one parsed JSON-RPC message.
+ *
+ * Returns the message to send back, or null when nothing is owed: a
+ * notification, or a response the client should not have sent.
+ */
+export declare function createMcpHandler(options: McpServerOptions): (message: unknown) => Promise<OutgoingMessage | null>;
+/**
+ * Serves a handler over newline-delimited JSON-RPC until the input ends.
+ *
+ * The whole stdio binding. Messages are split on `\n` with a trailing `\r`
+ * dropped, blank lines are skipped, and every response is written as a single
+ * line - `JSON.stringify` never emits a raw newline, which is what the binding
+ * requires. Requests are answered concurrently and in whatever order they
+ * finish. A request the client cancels gets no response at all. When the input
+ * closes, requests still running are allowed to finish and then this resolves.
+ */
+export declare function serveStdio(input: Readable, write: (line: string) => void, handle: (message: unknown) => Promise<OutgoingMessage | null>): Promise<void>;
+export {};
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

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