@descent-vtt/spec-guard 0.1.0

package/dist/glob.js

@@ -0,0 +1,238 @@
+/**
+ * Dependency-free glob matching and directory walking.
+ *
+ * Windows shells do not expand globs, so `spec-guard "docs/**\/*.md"` must
+ * behave identically on every platform. spec-guard therefore always expands
+ * patterns itself instead of trusting the shell.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+/** Directories never worth searching. Mirrors ripgrep's practical defaults. */
+export const DEFAULT_IGNORED_DIRECTORIES = new Set([
+    '.git',
+    '.hg',
+    '.svn',
+    '.cache',
+    '.next',
+    '.nuxt',
+    '.svelte-kit',
+    '.turbo',
+    '.venv',
+    '__pycache__',
+    'bower_components',
+    'build',
+    'coverage',
+    'dist',
+    'node_modules',
+    'out',
+    'venv',
+]);
+const MAGIC_RE = /[*?[\]{}]/;
+/** True when the pattern contains glob metacharacters. */
+export function isGlob(pattern) {
+    return MAGIC_RE.test(pattern);
+}
+/** Normalises Windows separators so every internal path uses `/`. */
+export function toPosix(value) {
+    return value.replace(/\\/g, '/');
+}
+const REGEXP_SPECIALS = new Set(['.', '+', '^', '$', '(', ')', '|', '\\']);
+/**
+ * Converts a glob to an anchored RegExp.
+ * Supports `*`, `**`, `?`, `[...]` and `{a,b}` - the subset every developer
+ * already knows from .gitignore and ripgrep.
+ */
+export function globToRegExp(pattern, options = {}) {
+    let source = '';
+    let index = 0;
+    const input = toPosix(pattern);
+    while (index < input.length) {
+        const char = input[index];
+        if (char === '*') {
+            if (input[index + 1] === '*') {
+                index += 2;
+                if (input[index] === '/') {
+                    index += 1;
+                    source += '(?:[^/]*\\/)*';
+                }
+                else {
+                    source += '.*';
+                }
+                continue;
+            }
+            source += '[^/]*';
+            index += 1;
+            continue;
+        }
+        if (char === '?') {
+            source += '[^/]';
+            index += 1;
+            continue;
+        }
+        if (char === '[') {
+            const close = input.indexOf(']', index + 1);
+            if (close === -1) {
+                source += '\\[';
+                index += 1;
+                continue;
+            }
+            let body = input.slice(index + 1, close);
+            if (body.startsWith('!'))
+                body = `^${body.slice(1)}`;
+            source += `[${body}]`;
+            index = close + 1;
+            continue;
+        }
+        if (char === '{') {
+            const close = input.indexOf('}', index + 1);
+            if (close === -1) {
+                source += '\\{';
+                index += 1;
+                continue;
+            }
+            const alternatives = input
+                .slice(index + 1, close)
+                .split(',')
+                .map((alternative) => globToRegExp(alternative, options).source.slice(1, -1));
+            source += `(?:${alternatives.join('|')})`;
+            index = close + 1;
+            continue;
+        }
+        source += REGEXP_SPECIALS.has(char) ? `\\${char}` : char;
+        index += 1;
+    }
+    return new RegExp(`^${source}$`, options.ignoreCase ? 'i' : '');
+}
+/**
+ * Builds a predicate over root-relative POSIX paths.
+ *
+ * Following ripgrep's `-g` semantics, a pattern without a `/` is matched
+ * against the file's basename (`*.ts` matches `src/deep/a.ts`), while a pattern
+ * containing `/` is matched against the whole relative path.
+ */
+export function createGlobMatcher(patterns) {
+    if (patterns.length === 0)
+        return () => true;
+    const matchers = patterns.map((pattern) => {
+        let normalized = toPosix(pattern).replace(/^\.\//, '');
+        if (normalized.endsWith('/'))
+            normalized += '**';
+        const basenameOnly = !normalized.includes('/');
+        return { regexp: globToRegExp(normalized), basenameOnly };
+    });
+    return (relativePath) => matchers.some(({ regexp, basenameOnly }) => regexp.test(basenameOnly ? path.posix.basename(relativePath) : relativePath));
+}
+/**
+ * Depth-first directory walk yielding regular files.
+ * Emits nothing when `root` is missing or is not a directory.
+ */
+export async function* walkFiles(root, options = {}) {
+    const ignored = options.ignoredDirectories ?? DEFAULT_IGNORED_DIRECTORIES;
+    const includeHidden = options.includeHidden ?? false;
+    const followSymlinks = options.followSymlinks ?? false;
+    const seen = new Set();
+    async function* visit(directory, prefix) {
+        let entries;
+        try {
+            entries = await fs.readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            const name = entry.name;
+            if (!includeHidden && name.startsWith('.'))
+                continue;
+            const absolutePath = path.join(directory, name);
+            const relativePath = prefix ? `${prefix}/${name}` : name;
+            let isDirectory = entry.isDirectory();
+            let isFile = entry.isFile();
+            if (entry.isSymbolicLink()) {
+                if (!followSymlinks)
+                    continue;
+                const stats = await fs.stat(absolutePath).catch(() => null);
+                if (!stats)
+                    continue;
+                isDirectory = stats.isDirectory();
+                isFile = stats.isFile();
+            }
+            if (isDirectory) {
+                if (ignored.has(name))
+                    continue;
+                // Each physical directory is visited at most once. That stops symlink
+                // cycles, and - more importantly for a search tool - stops a linked
+                // tree from counting the same match twice.
+                const real = followSymlinks ? await fs.realpath(absolutePath).catch(() => absolutePath) : absolutePath;
+                if (seen.has(real))
+                    continue;
+                seen.add(real);
+                yield* visit(absolutePath, relativePath);
+                continue;
+            }
+            if (!isFile)
+                continue;
+            const stats = await fs.stat(absolutePath).catch(() => null);
+            if (!stats)
+                continue;
+            yield { absolutePath, relativePath, size: stats.size };
+        }
+    }
+    const rootStats = await fs.stat(root).catch(() => null);
+    if (!rootStats?.isDirectory())
+        return;
+    yield* visit(root, '');
+}
+/** Longest leading directory of a glob that contains no metacharacters. */
+export function globBase(pattern) {
+    const segments = toPosix(pattern).split('/');
+    const base = [];
+    let index = 0;
+    for (; index < segments.length; index++) {
+        const segment = segments[index];
+        if (isGlob(segment) || index === segments.length - 1)
+            break;
+        base.push(segment);
+    }
+    return { base: base.join('/'), rest: segments.slice(index).join('/') };
+}
+/**
+ * Expands CLI spec patterns into a sorted, de-duplicated list of absolute file
+ * paths. Plain paths are taken literally; a directory expands to the Markdown
+ * files it contains.
+ */
+export async function expandSpecPatterns(patterns, root, defaultExtensions = ['.md', '.markdown', '.mdx']) {
+    const found = new Set();
+    for (const rawPattern of patterns) {
+        const pattern = toPosix(rawPattern);
+        if (!isGlob(pattern)) {
+            const absolute = path.resolve(root, pattern);
+            const stats = await fs.stat(absolute).catch(() => null);
+            if (stats?.isFile()) {
+                found.add(absolute);
+            }
+            else if (stats?.isDirectory()) {
+                for await (const file of walkFiles(absolute)) {
+                    if (defaultExtensions.some((extension) => file.relativePath.toLowerCase().endsWith(extension))) {
+                        found.add(file.absolutePath);
+                    }
+                }
+            }
+            continue;
+        }
+        const isAbsolutePattern = path.isAbsolute(pattern);
+        const { base } = globBase(pattern);
+        const walkRoot = isAbsolutePattern ? base || path.parse(pattern).root : path.resolve(root, base);
+        const matcher = createGlobMatcher([pattern]);
+        const includeHidden = pattern.split('/').some((segment) => segment.startsWith('.'));
+        for await (const file of walkFiles(walkRoot, { includeHidden })) {
+            const candidate = isAbsolutePattern
+                ? toPosix(file.absolutePath)
+                : toPosix(path.relative(root, file.absolutePath));
+            if (matcher(candidate))
+                found.add(file.absolutePath);
+        }
+    }
+    return [...found].sort();
+}
+//# sourceMappingURL=glob.js.map

package/dist/glob.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Programmatic API.
+ *
+ * The CLI is a thin shell over `runSpecGuard`; anything the CLI can do, a build
+ * script or a custom reporter can do too.
+ *
+ * ```ts
+ * import { runSpecGuard, formatReport } from '@descent-vtt/spec-guard';
+ *
+ * const report = await runSpecGuard({ patterns: ['docs/**\/*.md'], root: process.cwd() });
+ * if (!report.ok) console.error(formatReport(report, { color: true, verbose: false }));
+ * ```
+ */
+export { main, parseArgs, HELP, UsageError, EXIT_OK, EXIT_FAILED, EXIT_ERROR } from './cli.js';
+export type { CliIO, CliOptions } from './cli.js';
+export { buildJsRegExp, buildRipgrepArgs, createCachedEngine, escapeRegExp, findRipgrep, javascriptEngine, resetRipgrepProbe, resolveEngine, scanContent, MAX_FILE_SIZE, } from './engine.js';
+export type { Engine, EnginePreference, SearchRequest } from './engine.js';
+export { createGlobMatcher, expandSpecPatterns, globBase, globToRegExp, isGlob, toPosix, walkFiles, DEFAULT_IGNORED_DIRECTORIES, } from './glob.js';
+export type { WalkedFile, WalkOptions } from './glob.js';
+export { maskCode, parseAttributes, parseDirectives } from './parser.js';
+export type { ParseContext } from './parser.js';
+export { executeAssertion, resolveDirective, runSpecGuard, DEFAULT_CONCURRENCY, DEFAULT_MAX_SNIPPETS, } from './runner.js';
+export type { ResolveContext, RunOptions, RunResult } from './runner.js';
+export { createPainter, formatJson, formatReport, shouldUseAscii, shouldUseColor } from './reporter.js';
+export type { ReporterOptions } from './reporter.js';
+export type { Assertion, AssertionResult, Bounds, Directive, DirectiveError, DirectiveKind, EngineName, MatchLocation, ParseResult, RunReport, RunSummary, SearchOptions, SearchResult, SourceLocation, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC/F,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAElD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE3E,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,QAAQ,EACR,YAAY,EACZ,MAAM,EACN,OAAO,EACP,SAAS,EACT,2BAA2B,GAC5B,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACxG,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,YAAY,EACV,SAAS,EACT,eAAe,EACf,MAAM,EACN,SAAS,EACT,cAAc,EACd,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,EACX,SAAS,EACT,UAAU,EACV,aAAa,EACb,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * Programmatic API.
+ *
+ * The CLI is a thin shell over `runSpecGuard`; anything the CLI can do, a build
+ * script or a custom reporter can do too.
+ *
+ * ```ts
+ * import { runSpecGuard, formatReport } from '@descent-vtt/spec-guard';
+ *
+ * const report = await runSpecGuard({ patterns: ['docs/**\/*.md'], root: process.cwd() });
+ * if (!report.ok) console.error(formatReport(report, { color: true, verbose: false }));
+ * ```
+ */
+export { main, parseArgs, HELP, UsageError, EXIT_OK, EXIT_FAILED, EXIT_ERROR } from './cli.js';
+export { buildJsRegExp, buildRipgrepArgs, createCachedEngine, escapeRegExp, findRipgrep, javascriptEngine, resetRipgrepProbe, resolveEngine, scanContent, MAX_FILE_SIZE, } from './engine.js';
+export { createGlobMatcher, expandSpecPatterns, globBase, globToRegExp, isGlob, toPosix, walkFiles, DEFAULT_IGNORED_DIRECTORIES, } from './glob.js';
+export { maskCode, parseAttributes, parseDirectives } from './parser.js';
+export { executeAssertion, resolveDirective, runSpecGuard, DEFAULT_CONCURRENCY, DEFAULT_MAX_SNIPPETS, } from './runner.js';
+export { createPainter, formatJson, formatReport, shouldUseAscii, shouldUseColor } from './reporter.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAG/F,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,aAAa,GACd,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,QAAQ,EACR,YAAY,EACZ,MAAM,EACN,OAAO,EACP,SAAS,EACT,2BAA2B,GAC5B,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGzE,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/parser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Markdown directive parser.
+ *
+ * spec-guard directives are plain HTML comments, which means they are invisible
+ * in every Markdown renderer on earth and require no front-matter, no custom
+ * fences and no preprocessor:
+ *
+ *   <!-- @assert-absence target="src/" symbol="LegacyPaymentGateway" -->
+ *
+ * Two properties matter more than raw speed here:
+ *  1. Directives inside fenced code blocks or inline code spans are IGNORED, so
+ *     a README can document the syntax without executing it.
+ *  2. Anything that looks like a directive but is malformed is reported as an
+ *     error rather than silently skipped - a typo must never turn into a
+ *     silently-passing invariant.
+ */
+import type { ParseResult } from './types.js';
+export interface ParseContext {
+    /** Absolute path of the spec file. */
+    file: string;
+    /** Display path, relative to root, forward slashes. */
+    relativeFile: string;
+}
+/**
+ * Blanks out fenced code blocks and inline code spans, preserving every byte
+ * offset and newline so that reported line/column numbers stay exact.
+ */
+export declare function maskCode(source: string): string;
+/** Parses `name="value"` pairs; bare `name` is shorthand for `name="true"`. */
+export declare function parseAttributes(input: string): Record<string, string>;
+/** Extracts every spec-guard directive from a Markdown source string. */
+export declare function parseDirectives(source: string, context: ParseContext): ParseResult;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAA4C,WAAW,EAAkB,MAAM,YAAY,CAAC;AA0BxG,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAwD/C;AA0BD,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUrE;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,WAAW,CAkDlF"}

package/dist/parser.js

@@ -0,0 +1,180 @@
+/**
+ * Markdown directive parser.
+ *
+ * spec-guard directives are plain HTML comments, which means they are invisible
+ * in every Markdown renderer on earth and require no front-matter, no custom
+ * fences and no preprocessor:
+ *
+ *   <!-- @assert-absence target="src/" symbol="LegacyPaymentGateway" -->
+ *
+ * Two properties matter more than raw speed here:
+ *  1. Directives inside fenced code blocks or inline code spans are IGNORED, so
+ *     a README can document the syntax without executing it.
+ *  2. Anything that looks like a directive but is malformed is reported as an
+ *     error rather than silently skipped - a typo must never turn into a
+ *     silently-passing invariant.
+ */
+const KINDS = new Set(['assert-absence', 'assert-count', 'assert-present']);
+/** Attributes each directive kind accepts. */
+const ALLOWED_ATTRIBUTES = {
+    'assert-absence': new Set(['target', 'symbol', 'expected', 'max', 'glob', 'regex', 'word', 'ignore-case', 'reason']),
+    'assert-count': new Set([
+        'target',
+        'symbol',
+        'expected',
+        'min',
+        'max',
+        'glob',
+        'regex',
+        'word',
+        'ignore-case',
+        'reason',
+    ]),
+    'assert-present': new Set(['file', 'reason']),
+};
+const DIRECTIVE_RE = /<!--\s*@([a-zA-Z][\w-]*)([\s\S]*?)-->/g;
+const ATTRIBUTE_RE = /([a-zA-Z][\w-]*)(?:\s*=\s*(?:"((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)'|([^\s"'=<>`]+)))?/g;
+/**
+ * Blanks out fenced code blocks and inline code spans, preserving every byte
+ * offset and newline so that reported line/column numbers stay exact.
+ */
+export function maskCode(source) {
+    // split('') keeps UTF-16 index parity with the original string, which
+    // [...source] would break on astral characters (and break line numbers).
+    const chars = source.split('');
+    const blank = (start, end) => {
+        for (let i = start; i < end && i < chars.length; i++) {
+            if (chars[i] !== '\n')
+                chars[i] = ' ';
+        }
+    };
+    // Fenced code blocks: ``` or ~~~ (3+ markers), optionally indented up to 3 spaces.
+    const fenceRe = /^[ \t]{0,3}(`{3,}|~{3,})[^\n]*$/gm;
+    let match;
+    const fences = [];
+    while ((match = fenceRe.exec(source)) !== null) {
+        fences.push({ index: match.index, end: match.index + match[0].length, marker: match[1] });
+    }
+    const consumed = [];
+    for (let i = 0; i < fences.length; i++) {
+        const open = fences[i];
+        if (consumed.some(([s, e]) => open.index >= s && open.index < e))
+            continue;
+        const char = open.marker[0];
+        let closeEnd = source.length;
+        for (let j = i + 1; j < fences.length; j++) {
+            const candidate = fences[j];
+            if (candidate.marker[0] === char && candidate.marker.length >= open.marker.length) {
+                closeEnd = candidate.end;
+                break;
+            }
+        }
+        consumed.push([open.index, closeEnd]);
+        blank(open.index, closeEnd);
+    }
+    // Inline code spans, using CommonMark's rule: a run of N backticks is closed
+    // by the next run of EXACTLY N backticks. Runs of a different length are
+    // skipped rather than treated as a closer - otherwise a stray ``` inside a
+    // sentence shifts every later pairing by one and un-masks real prose.
+    const masked = chars.join('');
+    const runs = [];
+    const runRe = /`+/g;
+    let run;
+    while ((run = runRe.exec(masked)) !== null) {
+        runs.push({ index: run.index, length: run[0].length });
+    }
+    for (let index = 0; index < runs.length; index++) {
+        const open = runs[index];
+        const closeIndex = runs.findIndex((candidate, position) => position > index && candidate.length === open.length);
+        if (closeIndex === -1)
+            continue;
+        const close = runs[closeIndex];
+        blank(open.index, close.index + close.length);
+        index = closeIndex;
+    }
+    return chars.join('');
+}
+/** Pre-computed line starts, for O(log n) offset -> line/column resolution. */
+function lineStarts(source) {
+    const starts = [0];
+    for (let i = 0; i < source.length; i++) {
+        if (source[i] === '\n')
+            starts.push(i + 1);
+    }
+    return starts;
+}
+function locate(starts, index) {
+    let low = 0;
+    let high = starts.length - 1;
+    while (low < high) {
+        const mid = (low + high + 1) >> 1;
+        if (starts[mid] <= index)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return { line: low + 1, column: index - starts[low] + 1 };
+}
+function unescape(value) {
+    return value.replace(/\\(.)/g, '$1');
+}
+/** Parses `name="value"` pairs; bare `name` is shorthand for `name="true"`. */
+export function parseAttributes(input) {
+    const attributes = {};
+    ATTRIBUTE_RE.lastIndex = 0;
+    let match;
+    while ((match = ATTRIBUTE_RE.exec(input)) !== null) {
+        const name = match[1].toLowerCase();
+        const raw = match[2] ?? match[3] ?? match[4];
+        attributes[name] = raw === undefined ? 'true' : unescape(raw);
+    }
+    return attributes;
+}
+/** Extracts every spec-guard directive from a Markdown source string. */
+export function parseDirectives(source, context) {
+    const directives = [];
+    const errors = [];
+    const masked = maskCode(source);
+    const starts = lineStarts(source);
+    DIRECTIVE_RE.lastIndex = 0;
+    let match;
+    while ((match = DIRECTIVE_RE.exec(masked)) !== null) {
+        const kind = match[1].toLowerCase();
+        const body = match[2];
+        const raw = source.slice(match.index, match.index + match[0].length);
+        const position = locate(starts, match.index);
+        const location = {
+            file: context.file,
+            relativeFile: context.relativeFile,
+            line: position.line,
+            column: position.column,
+        };
+        if (!KINDS.has(kind)) {
+            // Only complain about things that clearly meant to be a directive.
+            if (kind.startsWith('assert')) {
+                errors.push({
+                    location,
+                    raw,
+                    message: `Unknown directive "@${kind}". Expected one of: ${[...KINDS].map((k) => `@${k}`).join(', ')}.`,
+                });
+            }
+            continue;
+        }
+        const attributes = parseAttributes(body);
+        const allowed = ALLOWED_ATTRIBUTES[kind];
+        const unknown = Object.keys(attributes).filter((name) => !allowed.has(name));
+        if (unknown.length > 0) {
+            errors.push({
+                location,
+                raw,
+                message: `Unknown attribute${unknown.length > 1 ? 's' : ''} ${unknown
+                    .map((name) => `"${name}"`)
+                    .join(', ')} on @${kind}. Allowed: ${[...allowed].join(', ')}.`,
+            });
+            continue;
+        }
+        directives.push({ kind: kind, attributes, location, raw });
+    }
+    return { directives, errors };
+}
+//# sourceMappingURL=parser.js.map

package/dist/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,MAAM,KAAK,GAAG,IAAI,GAAG,CAAS,CAAC,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAEpF,8CAA8C;AAC9C,MAAM,kBAAkB,GAA+C;IACrE,gBAAgB,EAAE,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;IACpH,cAAc,EAAE,IAAI,GAAG,CAAC;QACtB,QAAQ;QACR,QAAQ;QACR,UAAU;QACV,KAAK;QACL,KAAK;QACL,MAAM;QACN,OAAO;QACP,MAAM;QACN,aAAa;QACb,QAAQ;KACT,CAAC;IACF,gBAAgB,EAAE,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CAC9C,CAAC;AAEF,MAAM,YAAY,GAAG,wCAAwC,CAAC;AAC9D,MAAM,YAAY,GAChB,yFAAyF,CAAC;AAS5F;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc;IACrC,sEAAsE;IACtE,yEAAyE;IACzE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,GAAW,EAAQ,EAAE;QACjD,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACrD,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI;gBAAE,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;QACxC,CAAC;IACH,CAAC,CAAC;IAEF,mFAAmF;IACnF,MAAM,OAAO,GAAG,mCAAmC,CAAC;IACpD,IAAI,KAA6B,CAAC;IAClC,MAAM,MAAM,GAA0D,EAAE,CAAC;IACzE,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAW,EAAE,CAAC,CAAC;IACtG,CAAC;IACD,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAmD,CAAC;QACzE,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;YAAE,SAAS;QAC3E,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAW,CAAC;QACtC,IAAI,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAmD,CAAC;YAC9E,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,SAAS,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClF,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC;gBACzB,MAAM;YACR,CAAC;QACH,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAED,6EAA6E;IAC7E,yEAAyE;IACzE,2EAA2E;IAC3E,sEAAsE;IACtE,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9B,MAAM,IAAI,GAA6C,EAAE,CAAC;IAC1D,MAAM,KAAK,GAAG,KAAK,CAAC;IACpB,IAAI,GAA2B,CAAC;IAChC,OAAO,CAAC,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC3C,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAsC,CAAC;QAC9D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,GAAG,KAAK,IAAI,SAAS,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC,CAAC;QACjH,IAAI,UAAU,KAAK,CAAC,CAAC;YAAE,SAAS;QAChC,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAsC,CAAC;QACpE,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;QAC9C,KAAK,GAAG,UAAU,CAAC;IACrB,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxB,CAAC;AAED,+EAA+E;AAC/E,SAAS,UAAU,CAAC,MAAc;IAChC,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI;YAAE,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,MAAM,CAAC,MAAgB,EAAE,KAAa;IAC7C,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,IAAI,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAC7B,OAAO,GAAG,GAAG,IAAI,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,CAAC,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QAClC,IAAK,MAAM,CAAC,GAAG,CAAY,IAAI,KAAK;YAAE,GAAG,GAAG,GAAG,CAAC;;YAC3C,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,GAAI,MAAM,CAAC,GAAG,CAAY,GAAG,CAAC,EAAE,CAAC;AACxE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAa;IAC7B,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,MAAM,UAAU,GAA2B,EAAE,CAAC;IAC9C,YAAY,CAAC,SAAS,GAAG,CAAC,CAAC;IAC3B,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACnD,MAAM,IAAI,GAAI,KAAK,CAAC,CAAC,CAAY,CAAC,WAAW,EAAE,CAAC;QAChD,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;QAC7C,UAAU,CAAC,IAAI,CAAC,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,OAAqB;IACnE,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAElC,YAAY,CAAC,SAAS,GAAG,CAAC,CAAC;IAC3B,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACpD,MAAM,IAAI,GAAI,KAAK,CAAC,CAAC,CAAY,CAAC,WAAW,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAW,CAAC;QAChC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACrE,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAC7C,MAAM,QAAQ,GAAmB;YAC/B,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,MAAM,EAAE,QAAQ,CAAC,MAAM;SACxB,CAAC;QAEF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACrB,mEAAmE;YACnE,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC9B,MAAM,CAAC,IAAI,CAAC;oBACV,QAAQ;oBACR,GAAG;oBACH,OAAO,EAAE,uBAAuB,IAAI,uBAAuB,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;iBACxG,CAAC,CAAC;YACL,CAAC;YACD,SAAS;QACX,CAAC;QAED,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAqB,CAAC,CAAC;QAC1D,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7E,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,CAAC,IAAI,CAAC;gBACV,QAAQ;gBACR,GAAG;gBACH,OAAO,EAAE,oBAAoB,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,OAAO;qBAClE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC;qBAC1B,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,cAAc,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;aAClE,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAqB,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AAChC,CAAC"}

package/dist/reporter.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Terminal and JSON reporting.
+ *
+ * The failure block is the whole product: a spec author who broke an invariant
+ * should be able to fix it without opening a single file, so every failure
+ * carries the spec location, the expectation, the observed count and real
+ * snippets from the offending code.
+ */
+import type { RunResult } from './runner.js';
+export interface ReporterOptions {
+    color: boolean;
+    verbose: boolean;
+    /** Symbols safe for legacy Windows consoles. */
+    ascii?: boolean;
+}
+declare const ANSI: {
+    readonly reset: `${string}[0m`;
+    readonly bold: `${string}[1m`;
+    readonly dim: `${string}[2m`;
+    readonly red: `${string}[31m`;
+    readonly green: `${string}[32m`;
+    readonly yellow: `${string}[33m`;
+    readonly blue: `${string}[34m`;
+    readonly magenta: `${string}[35m`;
+    readonly cyan: `${string}[36m`;
+    readonly gray: `${string}[90m`;
+};
+type Style = keyof typeof ANSI;
+/** Creates a `paint(text, style)` helper honouring the color setting. */
+export declare function createPainter(color: boolean): (text: string, ...styles: Style[]) => string;
+/**
+ * Colour is on only when the stream is a TTY and nobody asked otherwise.
+ * Honours the NO_COLOR and FORCE_COLOR conventions.
+ */
+export declare function shouldUseColor(stream: {
+    isTTY?: boolean;
+}, flag: boolean | undefined, env?: NodeJS.ProcessEnv): boolean;
+/** Legacy Windows consoles render box-drawing glyphs poorly; degrade to ASCII. */
+export declare function shouldUseAscii(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/** Renders the full human-readable report. */
+export declare function formatReport(report: RunResult, options: ReporterOptions, maxSnippets?: number): string;
+/** Machine-readable output for CI consumers. */
+export declare function formatJson(report: RunResult): string;
+export {};
+//# sourceMappingURL=reporter.d.ts.map

package/dist/reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../src/reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAKD,QAAA,MAAM,IAAI;aACR,KAAK;aACL,IAAI;aACJ,GAAG;aACH,GAAG;aACH,KAAK;aACL,MAAM;aACN,IAAI;aACJ,OAAO;aACP,IAAI;aACJ,IAAI;CACI,CAAC;AAEX,KAAK,KAAK,GAAG,MAAM,OAAO,IAAI,CAAC;AAE/B,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,KAAK,MAAM,CAI1F;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,EAC3B,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAKT;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,QAAQ,kBAAmB,GAAG,OAAO,CAGzG;AA+ED,8CAA8C;AAC9C,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,eAAe,EAAE,WAAW,SAAI,GAAG,MAAM,CA6DjG;AAED,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CA4CpD"}