@descent-vtt/spec-guard 0.5.1 → 0.7.0

package/dist/graph.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The import graph behind `@assert-import-cycle`.
+ *
+ * Pure: no filesystem, no reading. The runner walks and tokenizes; everything
+ * here is a function of the references it was handed and the list of files the
+ * walk produced. That is the one thing ADR-0011 changed about resolution. A
+ * specifier is still turned into a path by arithmetic alone, as ADR-0005
+ * requires - but the path may now be compared with a set the run already holds,
+ * and that membership test is what gives a reference a file to point at.
+ *
+ * Layering lives elsewhere, in `layers.ts`, and on purpose. A layering rule
+ * matches names and never needs to know which file a reference is; a cycle
+ * cannot be seen without knowing exactly that. The two rest on different
+ * foundations, and keeping them in different modules keeps either from
+ * borrowing the other's.
+ */
+import { type ModuleReference } from './imports.js';
+/**
+ * Every file a relative specifier might mean, most likely first.
+ *
+ * The whole resolver, and deliberately short enough to read in one go: the
+ * TypeScript source of an emitted extension, the path as written, the path
+ * with an extension, the directory's index. No `tsconfig` paths, no `exports`
+ * maps, no guessing at a build - ADR-0011 has the table and the reasons.
+ */
+export declare function candidates(resolved: string): string[];
+/**
+ * Where a reference leads, as far as the graph is concerned.
+ *
+ * `edge` has a file. The other four do not, and they are distinguished because
+ * only one of them is a hole in the answer: `outside`, `not-code` and
+ * `external` are references the graph was never meant to follow, while
+ * `unresolved` is one it should have followed and could not.
+ */
+export type Resolution = {
+    kind: 'edge';
+    file: string;
+} | {
+    kind: 'outside';
+} | {
+    kind: 'not-code';
+} | {
+    kind: 'external';
+} | {
+    kind: 'unresolved';
+};
+export interface GraphScope {
+    /** The graph's nodes: JS and TS files in scope, root-relative, POSIX. */
+    nodes: ReadonlySet<string>;
+    /** Every file the walk produced, whatever its language. */
+    walked: ReadonlySet<string>;
+    /** Whether a root-relative path lies under one of the assertion's targets. */
+    covers: (relativePath: string) => boolean;
+    /** Whether a root-relative path is left out by the assertion's `exclude`. */
+    excluded: (relativePath: string) => boolean;
+}
+/** Resolves one specifier written in `importingFile` against the graph's scope. */
+export declare function resolveReference(specifier: string, importingFile: string, scope: GraphScope): Resolution;
+/** Whether a path is a file the graph can hold. */
+export declare function isGraphFile(relativePath: string): boolean;
+export interface GraphInput {
+    /** Root-relative path of the importing file. */
+    file: string;
+    references: readonly ModuleReference[];
+}
+export interface Unresolved {
+    file: string;
+    reference: ModuleReference;
+}
+export interface ImportGraph {
+    /** Every node, in path order. */
+    nodes: string[];
+    /** Out-edges of each node that has any, in path order, without duplicates. */
+    successors: Map<string, string[]>;
+    /** The first reference, in source order, that produced each edge. */
+    via: Map<string, ModuleReference>;
+    /** References that should have produced an edge and did not. */
+    unresolved: Unresolved[];
+}
+/** The key `via` stores an edge under. */
+export declare function edgeKey(from: string, to: string): string;
+/**
+ * Builds the graph from each file's references.
+ *
+ * Type-only references are left out when `includeTypes` is false, which is the
+ * difference between the coupling question and the runtime one - erased imports
+ * create no load-order cycle.
+ */
+export declare function buildGraph(inputs: readonly GraphInput[], scope: GraphScope, includeTypes: boolean): ImportGraph;
+/**
+ * Tarjan's strongly connected components, iteratively.
+ *
+ * The recursive form is the textbook one and recurses once per node on a
+ * dependency chain, so a long enough chain - a generated barrel file will make
+ * one - overflows the stack. Here the call stack is an explicit array of frames,
+ * each remembering how far through its out-edges it had got.
+ *
+ * Every component is returned, including the single nodes that are not in any
+ * cycle; `cyclicComponents` is the filter.
+ */
+export declare function stronglyConnected(nodes: readonly string[], successors: ReadonlyMap<string, readonly string[]>): string[][];
+/**
+ * The components that contain a cycle, each in path order, ordered by first
+ * member.
+ *
+ * A component of one node is a cycle only if that node imports itself. The
+ * ordering is for the report: the same tree yields the same list, whichever
+ * order the walk or the tokenizer happened to finish in.
+ */
+export declare function cyclicComponents(graph: Pick<ImportGraph, 'nodes' | 'successors'>): string[][];
+/**
+ * One concrete cycle through a component: the shortest through its first file.
+ *
+ * A component is a set, and nobody fixes a set. What someone changes is an
+ * import, so the report has to name the imports that close a loop. Breadth-first
+ * from the first file, confined to the component - a node outside it cannot lead
+ * back, so searching there costs time and cannot change the answer - and the
+ * first node reached that imports the start closes the shortest loop.
+ *
+ * Returned with the start at both ends: `[a, b, a]`, or `[a, a]` for a file that
+ * imports itself.
+ */
+export declare function witness(component: readonly string[], successors: ReadonlyMap<string, readonly string[]>): string[];
+//# sourceMappingURL=graph.d.ts.map

package/dist/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAenE;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CASrD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC;AAE3B,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,2DAA2D;IAC3D,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5B,8EAA8E;IAC9E,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1C,6EAA6E;IAC7E,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;CAC7C;AAmBD,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,CAoBxG;AAED,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAEzD;AAID,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,eAAe,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8EAA8E;IAC9E,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAClC,qEAAqE;IACrE,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAClC,gEAAgE;IAChE,UAAU,EAAE,UAAU,EAAE,CAAC;CAC1B;AAED,0CAA0C;AAC1C,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,GAAG,WAAW,CAsB/G;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,EAAE,CAiD1H;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,YAAY,CAAC,GAAG,MAAM,EAAE,EAAE,CAU7F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,CAyBlH"}

package/dist/graph.js

@@ -0,0 +1,241 @@
+/**
+ * The import graph behind `@assert-import-cycle`.
+ *
+ * Pure: no filesystem, no reading. The runner walks and tokenizes; everything
+ * here is a function of the references it was handed and the list of files the
+ * walk produced. That is the one thing ADR-0011 changed about resolution. A
+ * specifier is still turned into a path by arithmetic alone, as ADR-0005
+ * requires - but the path may now be compared with a set the run already holds,
+ * and that membership test is what gives a reference a file to point at.
+ *
+ * Layering lives elsewhere, in `layers.ts`, and on purpose. A layering rule
+ * matches names and never needs to know which file a reference is; a cycle
+ * cannot be seen without knowing exactly that. The two rest on different
+ * foundations, and keeping them in different modules keeps either from
+ * borrowing the other's.
+ */
+import path from 'node:path';
+import { comparePaths } from './engine.js';
+import { JS_EXTENSIONS } from './imports.js';
+/* --------------------------------------------------------------- resolution */
+/** What an emitted extension was compiled from, in the order TypeScript tries. */
+const SOURCE_EXTENSIONS = {
+    '.js': ['.ts', '.tsx'],
+    '.jsx': ['.tsx'],
+    '.mjs': ['.mts'],
+    '.cjs': ['.cts'],
+};
+/** Appended to an extensionless path, and to `/index`, in TypeScript's order. */
+const APPENDED_EXTENSIONS = ['.ts', '.tsx', '.d.ts', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts'];
+/**
+ * Every file a relative specifier might mean, most likely first.
+ *
+ * The whole resolver, and deliberately short enough to read in one go: the
+ * TypeScript source of an emitted extension, the path as written, the path
+ * with an extension, the directory's index. No `tsconfig` paths, no `exports`
+ * maps, no guessing at a build - ADR-0011 has the table and the reasons.
+ */
+export function candidates(resolved) {
+    const extension = path.posix.extname(resolved);
+    const stem = resolved.slice(0, resolved.length - extension.length);
+    return [
+        ...(SOURCE_EXTENSIONS[extension] ?? []).map((source) => `${stem}${source}`),
+        resolved,
+        ...APPENDED_EXTENSIONS.map((appended) => `${resolved}${appended}`),
+        ...APPENDED_EXTENSIONS.map((appended) => `${resolved}/index${appended}`),
+    ];
+}
+function isRelative(specifier) {
+    return specifier === '.' || specifier === '..' || specifier.startsWith('./') || specifier.startsWith('../');
+}
+/**
+ * A non-relative specifier that no package could be named.
+ *
+ * `#` is Node's prefix for imports private to the importing package, and `@/`,
+ * `~/` and a leading `/` are not valid package names. Something written that way
+ * has to be an alias for code inside the project, so an edge that cannot be
+ * followed is missing rather than absent. This is the only inference in the
+ * resolver, and it is made from npm's naming rules, not from anyone's config.
+ */
+function cannotBePackage(specifier) {
+    return /^(?:#|@\/|~\/|\/)/.test(specifier);
+}
+/** Resolves one specifier written in `importingFile` against the graph's scope. */
+export function resolveReference(specifier, importingFile, scope) {
+    if (!isRelative(specifier)) {
+        return cannotBePackage(specifier) ? { kind: 'unresolved' } : { kind: 'external' };
+    }
+    const resolved = path.posix.join(path.posix.dirname(importingFile), specifier).replace(/\/$/, '');
+    const names = candidates(resolved);
+    const file = names.find((candidate) => scope.nodes.has(candidate));
+    if (file !== undefined)
+        return { kind: 'edge', file };
+    // Every name for `exclude`, not only the path as written: `exclude="src/b.ts"`
+    // names the file and `./b.js` is what imports it, and tested against the
+    // specifier alone an excluded file looked like a broken import and failed
+    // --strict. Targets need no such care - a candidate only ever appends to the
+    // path, so it is under a target exactly when the path is.
+    if (!scope.covers(resolved) || names.some(scope.excluded))
+        return { kind: 'outside' };
+    // Membership, not an extension list. `./styles.css` that exists is not code;
+    // `./widget.service` that does not exist is a broken import, whatever its
+    // suffix happens to look like.
+    if (scope.walked.has(resolved))
+        return { kind: 'not-code' };
+    return { kind: 'unresolved' };
+}
+/** Whether a path is a file the graph can hold. */
+export function isGraphFile(relativePath) {
+    return JS_EXTENSIONS.has(path.posix.extname(relativePath));
+}
+/** The key `via` stores an edge under. */
+export function edgeKey(from, to) {
+    return `${from}\n${to}`;
+}
+/**
+ * Builds the graph from each file's references.
+ *
+ * Type-only references are left out when `includeTypes` is false, which is the
+ * difference between the coupling question and the runtime one - erased imports
+ * create no load-order cycle.
+ */
+export function buildGraph(inputs, scope, includeTypes) {
+    const targets = new Map();
+    const via = new Map();
+    const unresolved = [];
+    for (const { file, references } of inputs) {
+        for (const reference of references) {
+            if (reference.typeOnly && !includeTypes)
+                continue;
+            const resolution = resolveReference(reference.specifier, file, scope);
+            if (resolution.kind === 'unresolved')
+                unresolved.push({ file, reference });
+            if (resolution.kind !== 'edge')
+                continue;
+            const out = targets.get(file) ?? new Set();
+            targets.set(file, out);
+            out.add(resolution.file);
+            const key = edgeKey(file, resolution.file);
+            if (!via.has(key))
+                via.set(key, reference);
+        }
+    }
+    const successors = new Map([...targets].map(([file, out]) => [file, [...out].sort(comparePaths)]));
+    return { nodes: [...scope.nodes].sort(comparePaths), successors, via, unresolved };
+}
+/* ------------------------------------------------------------------- cycles */
+/**
+ * Tarjan's strongly connected components, iteratively.
+ *
+ * The recursive form is the textbook one and recurses once per node on a
+ * dependency chain, so a long enough chain - a generated barrel file will make
+ * one - overflows the stack. Here the call stack is an explicit array of frames,
+ * each remembering how far through its out-edges it had got.
+ *
+ * Every component is returned, including the single nodes that are not in any
+ * cycle; `cyclicComponents` is the filter.
+ */
+export function stronglyConnected(nodes, successors) {
+    const index = new Map();
+    const low = new Map();
+    const stack = [];
+    const onStack = new Set();
+    const components = [];
+    const visit = (node) => {
+        const order = index.size;
+        index.set(node, order);
+        low.set(node, order);
+        stack.push(node);
+        onStack.add(node);
+        return { node, next: 0 };
+    };
+    for (const start of nodes) {
+        if (index.has(start))
+            continue;
+        const frames = [visit(start)];
+        while (frames.length > 0) {
+            const frame = frames[frames.length - 1];
+            const out = successors.get(frame.node) ?? [];
+            if (frame.next < out.length) {
+                const next = out[frame.next++];
+                if (!index.has(next))
+                    frames.push(visit(next));
+                else if (onStack.has(next))
+                    low.set(frame.node, Math.min(low.get(frame.node), index.get(next)));
+                continue;
+            }
+            frames.pop();
+            const parent = frames[frames.length - 1];
+            if (parent)
+                low.set(parent.node, Math.min(low.get(parent.node), low.get(frame.node)));
+            if (low.get(frame.node) === index.get(frame.node)) {
+                const component = [];
+                let member;
+                do {
+                    member = stack.pop();
+                    onStack.delete(member);
+                    component.push(member);
+                } while (member !== frame.node);
+                components.push(component);
+            }
+        }
+    }
+    return components;
+}
+/**
+ * The components that contain a cycle, each in path order, ordered by first
+ * member.
+ *
+ * A component of one node is a cycle only if that node imports itself. The
+ * ordering is for the report: the same tree yields the same list, whichever
+ * order the walk or the tokenizer happened to finish in.
+ */
+export function cyclicComponents(graph) {
+    return stronglyConnected(graph.nodes, graph.successors)
+        .filter((component) => {
+        const first = component[0];
+        // A file with no imports is not in the map at all; `?.` says so rather
+        // than inventing an empty list for it to be absent from.
+        return component.length > 1 || graph.successors.get(first)?.includes(first) === true;
+    })
+        .map((component) => component.sort(comparePaths))
+        .sort((a, b) => comparePaths(a[0], b[0]));
+}
+/**
+ * One concrete cycle through a component: the shortest through its first file.
+ *
+ * A component is a set, and nobody fixes a set. What someone changes is an
+ * import, so the report has to name the imports that close a loop. Breadth-first
+ * from the first file, confined to the component - a node outside it cannot lead
+ * back, so searching there costs time and cannot change the answer - and the
+ * first node reached that imports the start closes the shortest loop.
+ *
+ * Returned with the start at both ends: `[a, b, a]`, or `[a, a]` for a file that
+ * imports itself.
+ */
+export function witness(component, successors) {
+    const start = component[0];
+    const members = new Set(component);
+    const previous = new Map();
+    const queue = [start];
+    // No `?? []` on these lookups. Every file in a cyclic component imports at
+    // least one other file in it - that is what being in one means - so the
+    // fallback could never be taken, and a branch nothing can reach reads exactly
+    // like one that something can.
+    const out = (node) => successors.get(node);
+    for (let at = 0; at < queue.length; at++) {
+        const node = queue[at];
+        for (const next of out(node)) {
+            if (!members.has(next) || previous.has(next))
+                continue;
+            previous.set(next, node);
+            queue.push(next);
+        }
+    }
+    const last = queue.find((node) => out(node).includes(start));
+    const loop = [start];
+    for (let node = last; node !== start; node = previous.get(node))
+        loop.splice(1, 0, node);
+    return [...loop, start];
+}
+//# sourceMappingURL=graph.js.map

package/dist/graph.js.map

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

package/dist/index.d.ts

@@ -12,23 +12,35 @@
  * ```
  */
 export { main, parseArgs, version, HELP, UsageError, EXIT_OK, EXIT_FAILED, EXIT_ERROR } from './cli.js';
-export type { CliIO, CliOptions, OutputFormat } from './cli.js';
+export type { CliIO, CliOptions, Command, OutputFormat } from './cli.js';
 export { buildJsRegExp, buildRipgrepArgs, createCachedEngine, enumerateCandidates, escapeRegExp, ANY_FILE_PROBE, findRipgrep, parseRipgrepErrors, isMissingBinary, javascriptEngine, resetRipgrepProbe, resolveEngine, runSearches, scanContent, sortLocations, MAX_FILE_SIZE, SMALL_TREE_BUDGET, } from './engine.js';
 export type { BatchEngine, CachedEngine, Engine, EnginePreference, Enumeration, EnumerationBudget, SearchRequest, } from './engine.js';
-export { compareDirents, createExcludeMatcher, createGlobMatcher, defaultDirectoryReader, expandSpecPatterns, globBase, globToRegExp, isGlob, toPosix, walkFiles, } from './glob.js';
-export type { DirectoryReader, WalkedFile, WalkOptions } from './glob.js';
+export { compareDirents, createExcludeMatcher, createGlobMatcher, defaultDirectoryReader, expandSpecPatterns, globBase, globToRegExp, isGlob, toPosix, walkFiles, walkPaths, } from './glob.js';
+export type { DirectoryReader, WalkedFile, WalkedPath, WalkOptions } from './glob.js';
 export { createScope, isBinary, mergeLedgers, tallyLedger, LedgerBuilder, DEFAULT_SCOPE, DEFAULT_SKIPPED_DIRECTORIES, MAX_LEDGER_ENTRIES, SCAN_EVERYTHING, UNCERTAIN_REASONS, } from './scope.js';
 export type { ScopeLedger, ScopePolicy, SkippedPath, SkipReason } from './scope.js';
 export { analyzeJavaScript, analyzeSource, createImportIndex, extractReferences, resolveModule, resolveSpecifier, tokenize, ANALYSABLE_EXTENSIONS, JS_EXTENSIONS, } from './imports.js';
 export type { AnalysisNote, FileImports, ImportIndex, ModuleReference, NoteKind, ReferenceKind } from './imports.js';
 export { analyzePolyglot, expandUsePath, languageFor, literalValue, logicalLines, matchingClose, normalizeModule, Reader, MAX_EXPANSION, POLYGLOT_EXTENSIONS, } from './polyglot.js';
 export type { ModuleLanguage } from './polyglot.js';
+export { buildGraph, candidates, cyclicComponents, edgeKey, isGraphFile, resolveReference, stronglyConnected, witness, } from './graph.js';
+export type { GraphInput, GraphScope, ImportGraph, Resolution, Unresolved } from './graph.js';
+export { checkLayers, layerMatcher } from './layers.js';
+export type { LayerInput, LayerReport, LayerViolation } from './layers.js';
 export { lineStarts, locate, maskRanges } from './text.js';
-export { maskCode, parseAttributes, parseDirectives } from './parser.js';
-export type { ParseContext } from './parser.js';
-export { applyBaseline, createScopeProbe, executeAssertion, resolveDirective, runSpecGuard, DEFAULT_CONCURRENCY, DEFAULT_MAX_SNIPPETS, } from './runner.js';
+export { maskCode, parseAttributes, parseDirectives, parseDocument, parseStatus, parseTitle, INACTIVE_STATUSES } from './parser.js';
+export type { ParseContext, ParsedDocument } from './parser.js';
+export { readSpecs, specPath } from './specs.js';
+export type { SpecDocument, SpecSet } from './specs.js';
+export { governs, layerPosition, viewRule, within } from './rules.js';
+export type { DocumentView, LayerPosition, PathShape, QueryPath, RuleView } from './rules.js';
+export { answerQuery, formatQuery, formatQueryJson, inQueriedPaths, loadRuleSet, queryRules, resolveQueryPath, viewDocument, QueryPathError, } from './query.js';
+export type { PathRules, QueryOptions, QueryReport, RuleSet, RuleSetOptions } from './query.js';
+export { classifyRequest, createMcpHandler, documentPath, documentUri, envelopeIssue, negotiateLegacyVersion, serveStdio, LEGACY_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS, RESOURCE_TEMPLATES, TOOLS, } from './mcp.js';
+export type { Era, McpServerOptions, OutgoingMessage } from './mcp.js';
+export { applyBaseline, createScopeProbe, executeAssertion, resolveDirective, runSpecGuard, specExclusions, DEFAULT_CONCURRENCY, DEFAULT_MAX_SNIPPETS, } from './runner.js';
 export type { ResolveContext, RunOptions, RunResult } from './runner.js';
 export { createPainter, formatBaselines, formatJson, formatReport, formatSarif, shouldUseAscii, shouldUseColor } from './reporter.js';
 export type { ReporterOptions } from './reporter.js';
-export type { Assertion, AssertionResult, BaselineEntry, Bounds, Directive, DirectiveError, DirectiveKind, EngineName, ImportQuery, MatchLocation, ParseResult, RatchetMode, RunReport, RunSummary, SearchOptions, SearchResult, SourceLocation, StaleBaselineEntry, } from './types.js';
+export type { Assertion, AssertionResult, BaselineEntry, Bounds, Directive, DirectiveError, DirectiveKind, EngineName, ImportQuery, InactiveSpec, MatchLocation, ParseResult, RatchetMode, RunReport, RunSummary, SearchOptions, SearchResult, SourceLocation, SpecStatus, StaleBaselineEntry, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -13,12 +13,18 @@
  */
 export { main, parseArgs, version, HELP, UsageError, EXIT_OK, EXIT_FAILED, EXIT_ERROR } from './cli.js';
 export { buildJsRegExp, buildRipgrepArgs, createCachedEngine, enumerateCandidates, escapeRegExp, ANY_FILE_PROBE, findRipgrep, parseRipgrepErrors, isMissingBinary, javascriptEngine, resetRipgrepProbe, resolveEngine, runSearches, scanContent, sortLocations, MAX_FILE_SIZE, SMALL_TREE_BUDGET, } from './engine.js';
-export { compareDirents, createExcludeMatcher, createGlobMatcher, defaultDirectoryReader, expandSpecPatterns, globBase, globToRegExp, isGlob, toPosix, walkFiles, } from './glob.js';
+export { compareDirents, createExcludeMatcher, createGlobMatcher, defaultDirectoryReader, expandSpecPatterns, globBase, globToRegExp, isGlob, toPosix, walkFiles, walkPaths, } from './glob.js';
 export { createScope, isBinary, mergeLedgers, tallyLedger, LedgerBuilder, DEFAULT_SCOPE, DEFAULT_SKIPPED_DIRECTORIES, MAX_LEDGER_ENTRIES, SCAN_EVERYTHING, UNCERTAIN_REASONS, } from './scope.js';
 export { analyzeJavaScript, analyzeSource, createImportIndex, extractReferences, resolveModule, resolveSpecifier, tokenize, ANALYSABLE_EXTENSIONS, JS_EXTENSIONS, } from './imports.js';
 export { analyzePolyglot, expandUsePath, languageFor, literalValue, logicalLines, matchingClose, normalizeModule, Reader, MAX_EXPANSION, POLYGLOT_EXTENSIONS, } from './polyglot.js';
+export { buildGraph, candidates, cyclicComponents, edgeKey, isGraphFile, resolveReference, stronglyConnected, witness, } from './graph.js';
+export { checkLayers, layerMatcher } from './layers.js';
 export { lineStarts, locate, maskRanges } from './text.js';
-export { maskCode, parseAttributes, parseDirectives } from './parser.js';
-export { applyBaseline, createScopeProbe, executeAssertion, resolveDirective, runSpecGuard, DEFAULT_CONCURRENCY, DEFAULT_MAX_SNIPPETS, } from './runner.js';
+export { maskCode, parseAttributes, parseDirectives, parseDocument, parseStatus, parseTitle, INACTIVE_STATUSES } from './parser.js';
+export { readSpecs, specPath } from './specs.js';
+export { governs, layerPosition, viewRule, within } from './rules.js';
+export { answerQuery, formatQuery, formatQueryJson, inQueriedPaths, loadRuleSet, queryRules, resolveQueryPath, viewDocument, QueryPathError, } from './query.js';
+export { classifyRequest, createMcpHandler, documentPath, documentUri, envelopeIssue, negotiateLegacyVersion, serveStdio, LEGACY_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS, RESOURCE_TEMPLATES, TOOLS, } from './mcp.js';
+export { applyBaseline, createScopeProbe, executeAssertion, resolveDirective, runSpecGuard, specExclusions, DEFAULT_CONCURRENCY, DEFAULT_MAX_SNIPPETS, } from './runner.js';
 export { createPainter, formatBaselines, formatJson, formatReport, formatSarif, shouldUseAscii, shouldUseColor } from './reporter.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGxG,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,WAAW,EACX,aAAa,EACb,aAAa,EACb,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAWrB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,QAAQ,EACR,YAAY,EACZ,MAAM,EACN,OAAO,EACP,SAAS,GACV,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,aAAa,EACb,aAAa,EACb,2BAA2B,EAC3B,kBAAkB,EAClB,eAAe,EACf,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,QAAQ,EACR,qBAAqB,EACrB,aAAa,GACd,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,eAAe,EACf,aAAa,EACb,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,eAAe,EACf,MAAM,EACN,aAAa,EACb,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE3D,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGzE,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGxG,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,WAAW,EACX,aAAa,EACb,aAAa,EACb,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAWrB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,QAAQ,EACR,YAAY,EACZ,MAAM,EACN,OAAO,EACP,SAAS,EACT,SAAS,GACV,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,aAAa,EACb,aAAa,EACb,2BAA2B,EAC3B,kBAAkB,EAClB,eAAe,EACf,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,QAAQ,EACR,qBAAqB,EACrB,aAAa,GACd,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,eAAe,EACf,aAAa,EACb,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,eAAe,EACf,MAAM,EACN,aAAa,EACb,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,OAAO,GACR,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGxD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE3D,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGpI,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGjD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGtE,OAAO,EACL,WAAW,EACX,WAAW,EACX,eAAe,EACf,cAAc,EACd,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,sBAAsB,EACtB,UAAU,EACV,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,KAAK,GACN,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/layers.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 { type ModuleReference } from './imports.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 declare function referenceForms(specifier: string, importingFile: string): string[];
+export interface LayerInput {
+    /** Root-relative path of the importing file. */
+    file: string;
+    references: readonly ModuleReference[];
+}
+export interface LayerViolation {
+    file: string;
+    /** The layer the file belongs to, as an index into the order. */
+    from: number;
+    /** The latest layer its reference reaches, also an index. */
+    to: number;
+    /** The first reference, in source order, that reaches a later layer. */
+    reference: ModuleReference;
+}
+export interface LayerReport {
+    /** Files in scope matched by each layer, by index. */
+    members: number[];
+    /** Files in scope that no layer matches, and which are therefore unconstrained. */
+    unassigned: string[];
+    /** Files matched by more than one layer, with every layer that matched. */
+    ambiguous: Array<{
+        file: string;
+        layers: number[];
+    }>;
+    /** At most one per file. */
+    violations: LayerViolation[];
+}
+/** A function from a path to the indices of every layer that matches it. */
+export declare function layerMatcher(order: readonly string[]): (relativePath: string) => number[];
+/**
+ * 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 declare function checkLayers(inputs: readonly LayerInput[], order: readonly string[], includeTypes: boolean): LayerReport;
+//# sourceMappingURL=layers.d.ts.map

package/dist/layers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layers.d.ts","sourceRoot":"","sources":["../src/layers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAGnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,CAKjF;AAED,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,wEAAwE;IACxE,SAAS,EAAE,eAAe,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mFAAmF;IACnF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,2EAA2E;IAC3E,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACrD,4BAA4B;IAC5B,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,YAAY,EAAE,MAAM,KAAK,MAAM,EAAE,CAIzF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,YAAY,EAAE,OAAO,GAAG,WAAW,CA6CvH"}