@timiagama/ecr 0.0.1 → 0.1.0

package/dist/bin.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * ECR Executable Entry Point
+ *
+ * This file runs the CLI unconditionally and does nothing else. It must not
+ * guard itself with a "was I invoked directly?" check that compares
+ * `process.argv[1]` with this module's path: package managers install the
+ * binary as a symlink (`node_modules/.bin/ecr`), Node resolves the module to
+ * its real path, and the two never match, so a guarded entry point silently
+ * exits 0 without running. Keeping the commands in `cli.ts` and the side
+ * effect here removes the need for any such check.
+ *
+ * It is also where supervision is asked for, because this file knows the one
+ * thing a supervised run needs: the script a child process would have to run,
+ * which is this file itself, at its real path rather than through whatever
+ * symlink invoked it. A host embedding the library instead of the command
+ * gets no supervision, and bounds its own work.
+ */
+import { fileURLToPath } from 'node:url';
+import { EcrCommandLine } from './cli.js';
+const result = new EcrCommandLine({
+    supervision: { entryPoint: fileURLToPath(import.meta.url) },
+}).run(process.argv.slice(2));
+process[result.stream].write(result.output);
+process.exitCode = result.exitCode;
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG1C,MAAM,MAAM,GAAmB,IAAI,cAAc,CAAC;IAChD,WAAW,EAAE,EAAE,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;CAC5D,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9B,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC5C,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC"}

package/dist/cli/corpus-loader.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Corpus Loading
+ *
+ * File discovery is the host's responsibility, not the linter's. This module
+ * is the CLI's implementation of that responsibility: it walks a directory,
+ * excludes meta-documents, and produces the inputs the linter consumes.
+ */
+import type { CorpusDocumentInput } from '../ecr.js';
+/**
+ * A path the walk reached but could not read.
+ */
+export interface UnreadablePath {
+    /** Corpus-relative path, with forward slashes. */
+    readonly path: string;
+    /** Why it could not be read: the file system's error code, or its message. */
+    readonly reason: string;
+}
+/**
+ * The outcome of walking a corpus directory.
+ */
+export interface LoadedCorpus {
+    /** Documents to validate, in path order. */
+    readonly documents: readonly CorpusDocumentInput[];
+    /**
+     * Corpus-relative paths excluded as meta-documents or by ignore pattern. A
+     * directory excluded whole by a pattern is listed once, with a trailing
+     * slash, and is not walked.
+     */
+    readonly excludedPaths: readonly string[];
+    /**
+     * Links beneath the corpus root that were not followed: every link to a
+     * directory, every link named like a document, and every link whose target
+     * is missing.
+     */
+    readonly notFollowedPaths: readonly string[];
+    /**
+     * Paths that could not be read. A corpus with any of these was not fully
+     * read, so its validation result cannot stand for the whole corpus.
+     */
+    readonly unreadablePaths: readonly UnreadablePath[];
+    /**
+     * Whether the project's `.ecrignore` excludes the corpus root itself, in
+     * which case nothing beneath it was walked.
+     */
+    readonly rootExcluded: boolean;
+}
+/**
+ * A project's own ignore patterns, from its `.ecrignore`, and the directory
+ * they are relative to.
+ */
+export interface ProjectIgnore {
+    /** The project root: the directory the command runs from. */
+    readonly workingDirectory: string;
+    /** Patterns relative to the working directory. */
+    readonly patterns: readonly string[];
+}
+/**
+ * Discovers and reads the Markdown documents of a corpus.
+ *
+ * Paths are reported relative to the corpus root and normalised to forward
+ * slashes, so that ignore patterns and diagnostics read the same on every
+ * platform.
+ *
+ * Symbolic links and junctions beneath the root are not followed, because the
+ * published recursive searches (`rg`, `grep -r`) do not follow them: a
+ * document reached only through a link would be validated but could not be
+ * found (1#9.11). A root that is itself a link is followed, as both search
+ * engines follow a link named on their command line.
+ */
+export declare class CorpusLoader {
+    /** Absolute or relative path to the corpus root directory. */
+    private readonly corpusRoot;
+    /** Decides which discovered documents are excluded from validation. */
+    private readonly metaDocumentFilter;
+    /**
+     * Applies the project's `.ecrignore` patterns, which are relative to the
+     * working directory rather than the corpus root; absent when there are none.
+     */
+    private readonly projectFilter;
+    /** The directory the project's patterns are relative to. */
+    private readonly workingDirectory;
+    /**
+     * Creates a loader for one corpus directory.
+     *
+     * @param corpusRoot - Path to the directory to walk
+     * @param ignorePatterns - Glob patterns relative to the corpus root, from `--ignore`
+     * @param projectIgnore - The project's `.ecrignore` patterns, relative to the working directory
+     */
+    constructor(corpusRoot: string, ignorePatterns?: readonly string[], projectIgnore?: ProjectIgnore);
+    /**
+     * Walks the corpus root and reads every Markdown document that is not
+     * excluded.
+     *
+     * A path that cannot be read is recorded and the walk continues, so that
+     * every such path is reported at once.
+     *
+     * @returns The documents to validate, and the paths excluded, not followed, or not readable
+     */
+    load(): LoadedCorpus;
+    /**
+     * Orders two corpus-relative paths by their UTF-16 code units, as
+     * `Array.prototype.sort` does by default.
+     *
+     * @param left - A path
+     * @param right - Another path
+     * @returns Negative, zero or positive, as for a sort comparator
+     */
+    private static comparePaths;
+    /**
+     * Walks one directory, in name order.
+     *
+     * @param directory - Directory to walk
+     * @param walk - What the walk has found so far
+     */
+    private walkDirectory;
+    /**
+     * Walks one directory entry: a link is recorded and not followed, a
+     * directory is descended into unless an ignore pattern excludes it whole,
+     * and a Markdown file is read unless it is excluded.
+     *
+     * @param entryPath - Path of the entry
+     * @param entryName - The entry's own name
+     * @param walk - What the walk has found so far
+     */
+    private walkEntry;
+    /**
+     * Records a link without following it. An ignore pattern covering it
+     * excludes it instead; a link to a file that is not Markdown is of no
+     * interest, as it could never be a document.
+     *
+     * @param entryPath - Path of the link
+     * @param entryName - The link's own name
+     * @param relativePath - The link's corpus-relative path
+     * @param walk - What the walk has found so far
+     */
+    private recordLink;
+    /**
+     * Determines whether an ignore pattern of either kind covers a path whose
+     * kind cannot or need not be known, such as a link or a vanished entry.
+     *
+     * @param relativePath - Corpus-relative path
+     * @param entryPath - Path of the entry, for the project's patterns
+     * @returns `true` when a file pattern or a whole-directory pattern covers it
+     */
+    private tellExcludedWhateverItIs;
+    /**
+     * Determines whether a `.ecrignore` pattern excludes the corpus root, either
+     * itself or through a directory above it: with `ecr/**` ignored, a root of
+     * `ecr/sub` is excluded as surely as `ecr`.
+     *
+     * @returns `true` when the root, or any directory between it and the project root, is excluded whole
+     */
+    private tellProjectExcludesRoot;
+    /**
+     * Determines whether a `.ecrignore` pattern excludes a whole directory.
+     *
+     * @param directoryPath - Path of the directory
+     * @returns `true` when the project's patterns cover everything beneath it
+     */
+    private tellProjectExcludesDirectory;
+    /**
+     * Determines whether a `.ecrignore` pattern excludes a file.
+     *
+     * @param filePath - Path of the file
+     * @returns `true` when one of the project's patterns matches it
+     */
+    private tellProjectExcludesFile;
+    /**
+     * Converts a path into one relative to the working directory, with forward
+     * slashes, which is what `.ecrignore` patterns are matched against.
+     *
+     * @param path - A path
+     * @returns The path relative to the working directory, or `undefined` when there are no project patterns or the path lies outside the project
+     */
+    private toProjectRelativePath;
+    /**
+     * Determines whether a name is a Markdown document's.
+     *
+     * @param entryName - A file or link name
+     * @returns `true` for a `.md` name, in any case
+     */
+    private static tellMarkdownName;
+    /**
+     * Determines whether a link resolves to something other than a directory.
+     *
+     * @param linkPath - Path of the link
+     * @returns `true` when the target exists and is not a directory
+     */
+    private static tellLinksToFile;
+    /**
+     * Converts an absolute path into a corpus-relative path with forward slashes.
+     *
+     * @param absolutePath - A path beneath the corpus root
+     * @returns The path relative to the corpus root
+     */
+    private toCorpusRelativePath;
+}
+//# sourceMappingURL=corpus-loader.d.ts.map

package/dist/cli/corpus-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus-loader.d.ts","sourceRoot":"","sources":["../../src/cli/corpus-loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAuBD;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY;IACvB,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IAExD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiC;IAE/D,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IAEtD;;;;;;OAMG;gBAED,UAAU,EAAE,MAAM,EAClB,cAAc,GAAE,SAAS,MAAM,EAAO,EACtC,aAAa,CAAC,EAAE,aAAa;IAU/B;;;;;;;;OAQG;IACI,IAAI,IAAI,YAAY;IAgC3B;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAQ3B;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAqBrB;;;;;;;;OAQG;IACH,OAAO,CAAC,SAAS;IAyDjB;;;;;;;;;OASG;IACH,OAAO,CAAC,UAAU;IAkBlB;;;;;;;OAOG;IACH,OAAO,CAAC,wBAAwB;IAShC;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAc/B;;;;;OAKG;IACH,OAAO,CAAC,4BAA4B;IAOpC;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAM/B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAe7B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAI/B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAQ9B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;CAU7B"}

package/dist/cli/corpus-loader.js

@@ -0,0 +1,351 @@
+/**
+ * Corpus Loading
+ *
+ * File discovery is the host's responsibility, not the linter's. This module
+ * is the CLI's implementation of that responsibility: it walks a directory,
+ * excludes meta-documents, and produces the inputs the linter consumes.
+ */
+import { lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+import { MetaDocumentFilter } from '../meta-documents.js';
+/**
+ * Directory-walking characters that mark a path as hidden on every platform
+ * this runs on. Hidden directories are skipped so that `.git`, `.obsidian` and
+ * similar never reach the linter.
+ */
+const HIDDEN_PREFIX = '.';
+/**
+ * The directory package managers install dependencies into. It is skipped
+ * wherever the walk meets it: an installed copy of this package carries the
+ * specification, whose DocIDs would collide with a project's own, and any
+ * other package's Markdown is not the project's documentation. A corpus root
+ * named explicitly is still walked, even inside one.
+ */
+const DEPENDENCY_DIRECTORY = 'node_modules';
+/**
+ * Extension identifying a Markdown document.
+ */
+const MARKDOWN_EXTENSION = '.md';
+/**
+ * Discovers and reads the Markdown documents of a corpus.
+ *
+ * Paths are reported relative to the corpus root and normalised to forward
+ * slashes, so that ignore patterns and diagnostics read the same on every
+ * platform.
+ *
+ * Symbolic links and junctions beneath the root are not followed, because the
+ * published recursive searches (`rg`, `grep -r`) do not follow them: a
+ * document reached only through a link would be validated but could not be
+ * found (1#9.11). A root that is itself a link is followed, as both search
+ * engines follow a link named on their command line.
+ */
+export class CorpusLoader {
+    /** Absolute or relative path to the corpus root directory. */
+    corpusRoot;
+    /** Decides which discovered documents are excluded from validation. */
+    metaDocumentFilter;
+    /**
+     * Applies the project's `.ecrignore` patterns, which are relative to the
+     * working directory rather than the corpus root; absent when there are none.
+     */
+    projectFilter;
+    /** The directory the project's patterns are relative to. */
+    workingDirectory;
+    /**
+     * Creates a loader for one corpus directory.
+     *
+     * @param corpusRoot - Path to the directory to walk
+     * @param ignorePatterns - Glob patterns relative to the corpus root, from `--ignore`
+     * @param projectIgnore - The project's `.ecrignore` patterns, relative to the working directory
+     */
+    constructor(corpusRoot, ignorePatterns = [], projectIgnore) {
+        this.corpusRoot = corpusRoot;
+        this.metaDocumentFilter = new MetaDocumentFilter(ignorePatterns);
+        // No meta-document names: those are already applied by the corpus filter.
+        this.projectFilter =
+            projectIgnore === undefined ? undefined : new MetaDocumentFilter(projectIgnore.patterns, []);
+        this.workingDirectory = projectIgnore?.workingDirectory;
+    }
+    /**
+     * Walks the corpus root and reads every Markdown document that is not
+     * excluded.
+     *
+     * A path that cannot be read is recorded and the walk continues, so that
+     * every such path is reported at once.
+     *
+     * @returns The documents to validate, and the paths excluded, not followed, or not readable
+     */
+    load() {
+        const walk = new CorpusWalk();
+        const rootExcluded = this.tellProjectExcludesRoot();
+        if (!rootExcluded) {
+            this.walkDirectory(this.corpusRoot, walk);
+        }
+        // Sorted by corpus-relative path, so the order is the same on every
+        // platform whatever the path separator.
+        walk.documents.sort((left, right) => CorpusLoader.comparePaths(left.uri, right.uri));
+        walk.excludedPaths.sort((left, right) => CorpusLoader.comparePaths(left, right));
+        walk.notFollowedPaths.sort((left, right) => CorpusLoader.comparePaths(left, right));
+        walk.unreadablePaths.sort((left, right) => CorpusLoader.comparePaths(left.path, right.path));
+        return {
+            documents: walk.documents,
+            excludedPaths: walk.excludedPaths,
+            notFollowedPaths: walk.notFollowedPaths,
+            unreadablePaths: walk.unreadablePaths,
+            rootExcluded,
+        };
+    }
+    /**
+     * Orders two corpus-relative paths by their UTF-16 code units, as
+     * `Array.prototype.sort` does by default.
+     *
+     * @param left - A path
+     * @param right - Another path
+     * @returns Negative, zero or positive, as for a sort comparator
+     */
+    static comparePaths(left, right) {
+        if (left === right) {
+            return 0;
+        }
+        return left < right ? -1 : 1;
+    }
+    /**
+     * Walks one directory, in name order.
+     *
+     * @param directory - Directory to walk
+     * @param walk - What the walk has found so far
+     */
+    walkDirectory(directory, walk) {
+        let entryNames;
+        try {
+            entryNames = readdirSync(directory).sort((left, right) => CorpusLoader.comparePaths(left, right));
+        }
+        catch (error) {
+            walk.recordUnreadable(this.toCorpusRelativePath(directory), error);
+            return;
+        }
+        for (const entryName of entryNames) {
+            if (entryName.startsWith(HIDDEN_PREFIX)) {
+                continue;
+            }
+            this.walkEntry(join(directory, entryName), entryName, walk);
+        }
+    }
+    /**
+     * Walks one directory entry: a link is recorded and not followed, a
+     * directory is descended into unless an ignore pattern excludes it whole,
+     * and a Markdown file is read unless it is excluded.
+     *
+     * @param entryPath - Path of the entry
+     * @param entryName - The entry's own name
+     * @param walk - What the walk has found so far
+     */
+    walkEntry(entryPath, entryName, walk) {
+        const relativePath = this.toCorpusRelativePath(entryPath);
+        let entryStats;
+        try {
+            entryStats = lstatSync(entryPath);
+        }
+        catch (error) {
+            if (this.tellExcludedWhateverItIs(relativePath, entryPath)) {
+                walk.excludedPaths.push(relativePath);
+                return;
+            }
+            walk.recordUnreadable(relativePath, error);
+            return;
+        }
+        if (entryStats.isSymbolicLink()) {
+            this.recordLink(entryPath, entryName, relativePath, walk);
+            return;
+        }
+        if (entryStats.isDirectory()) {
+            if (entryName === DEPENDENCY_DIRECTORY ||
+                this.metaDocumentFilter.excludesDirectory(relativePath) ||
+                this.tellProjectExcludesDirectory(entryPath)) {
+                walk.excludedPaths.push(`${relativePath}/`);
+                return;
+            }
+            this.walkDirectory(entryPath, walk);
+            return;
+        }
+        if (!CorpusLoader.tellMarkdownName(entryName)) {
+            return;
+        }
+        if (this.metaDocumentFilter.shouldExclude(relativePath) ||
+            this.tellProjectExcludesFile(entryPath)) {
+            walk.excludedPaths.push(relativePath);
+            return;
+        }
+        try {
+            walk.documents.push({
+                uri: relativePath,
+                markdownText: readFileSync(entryPath, 'utf8'),
+            });
+        }
+        catch (error) {
+            walk.recordUnreadable(relativePath, error);
+        }
+    }
+    /**
+     * Records a link without following it. An ignore pattern covering it
+     * excludes it instead; a link to a file that is not Markdown is of no
+     * interest, as it could never be a document.
+     *
+     * @param entryPath - Path of the link
+     * @param entryName - The link's own name
+     * @param relativePath - The link's corpus-relative path
+     * @param walk - What the walk has found so far
+     */
+    recordLink(entryPath, entryName, relativePath, walk) {
+        if (this.tellExcludedWhateverItIs(relativePath, entryPath)) {
+            walk.excludedPaths.push(relativePath);
+            return;
+        }
+        if (!CorpusLoader.tellMarkdownName(entryName) && CorpusLoader.tellLinksToFile(entryPath)) {
+            return;
+        }
+        walk.notFollowedPaths.push(relativePath);
+    }
+    /**
+     * Determines whether an ignore pattern of either kind covers a path whose
+     * kind cannot or need not be known, such as a link or a vanished entry.
+     *
+     * @param relativePath - Corpus-relative path
+     * @param entryPath - Path of the entry, for the project's patterns
+     * @returns `true` when a file pattern or a whole-directory pattern covers it
+     */
+    tellExcludedWhateverItIs(relativePath, entryPath) {
+        return (this.metaDocumentFilter.excludesDirectory(relativePath) ||
+            this.metaDocumentFilter.matchesIgnorePattern(relativePath) ||
+            this.tellProjectExcludesDirectory(entryPath) ||
+            this.tellProjectExcludesFile(entryPath));
+    }
+    /**
+     * Determines whether a `.ecrignore` pattern excludes the corpus root, either
+     * itself or through a directory above it: with `ecr/**` ignored, a root of
+     * `ecr/sub` is excluded as surely as `ecr`.
+     *
+     * @returns `true` when the root, or any directory between it and the project root, is excluded whole
+     */
+    tellProjectExcludesRoot() {
+        const projectPath = this.toProjectRelativePath(this.corpusRoot);
+        if (projectPath === undefined || projectPath === '') {
+            return false;
+        }
+        const segments = projectPath.split('/');
+        return segments.some((_segment, index) => this.projectFilter?.excludesDirectory(segments.slice(0, index + 1).join('/')) === true);
+    }
+    /**
+     * Determines whether a `.ecrignore` pattern excludes a whole directory.
+     *
+     * @param directoryPath - Path of the directory
+     * @returns `true` when the project's patterns cover everything beneath it
+     */
+    tellProjectExcludesDirectory(directoryPath) {
+        const projectPath = this.toProjectRelativePath(directoryPath);
+        return projectPath !== undefined && projectPath !== '' &&
+            this.projectFilter?.excludesDirectory(projectPath) === true;
+    }
+    /**
+     * Determines whether a `.ecrignore` pattern excludes a file.
+     *
+     * @param filePath - Path of the file
+     * @returns `true` when one of the project's patterns matches it
+     */
+    tellProjectExcludesFile(filePath) {
+        const projectPath = this.toProjectRelativePath(filePath);
+        return projectPath !== undefined && this.projectFilter?.matchesIgnorePattern(projectPath) === true;
+    }
+    /**
+     * Converts a path into one relative to the working directory, with forward
+     * slashes, which is what `.ecrignore` patterns are matched against.
+     *
+     * @param path - A path
+     * @returns The path relative to the working directory, or `undefined` when there are no project patterns or the path lies outside the project
+     */
+    toProjectRelativePath(path) {
+        if (this.workingDirectory === undefined) {
+            return undefined;
+        }
+        const projectPath = relative(this.workingDirectory, path);
+        // The project's patterns say nothing about paths outside the project.
+        if (isAbsolute(projectPath) || /^\.\.(?:[\\/]|$)/.test(projectPath)) {
+            return undefined;
+        }
+        return projectPath.replaceAll('\\', '/');
+    }
+    /**
+     * Determines whether a name is a Markdown document's.
+     *
+     * @param entryName - A file or link name
+     * @returns `true` for a `.md` name, in any case
+     */
+    static tellMarkdownName(entryName) {
+        return entryName.toLowerCase().endsWith(MARKDOWN_EXTENSION);
+    }
+    /**
+     * Determines whether a link resolves to something other than a directory.
+     *
+     * @param linkPath - Path of the link
+     * @returns `true` when the target exists and is not a directory
+     */
+    static tellLinksToFile(linkPath) {
+        try {
+            return !statSync(linkPath).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Converts an absolute path into a corpus-relative path with forward slashes.
+     *
+     * @param absolutePath - A path beneath the corpus root
+     * @returns The path relative to the corpus root
+     */
+    toCorpusRelativePath(absolutePath) {
+        const withoutRoot = absolutePath.startsWith(this.corpusRoot)
+            ? absolutePath.slice(this.corpusRoot.length)
+            : absolutePath;
+        return withoutRoot
+            .split('\\')
+            .join('/')
+            .replace(/^\/+/, '');
+    }
+}
+/**
+ * What one walk of a corpus has found so far.
+ */
+class CorpusWalk {
+    /** Documents read, in the order reached. */
+    documents = [];
+    /** Paths excluded as meta-documents or by ignore pattern. */
+    excludedPaths = [];
+    /** Links recorded and not followed. */
+    notFollowedPaths = [];
+    /** Paths reached but not readable. */
+    unreadablePaths = [];
+    /**
+     * Records a path that could not be read.
+     *
+     * @param path - The corpus-relative path; empty for the corpus root itself
+     * @param error - What reading it threw
+     */
+    recordUnreadable(path, error) {
+        this.unreadablePaths.push({ path: path === '' ? '.' : path, reason: CorpusWalk.showReason(error) });
+    }
+    /**
+     * Describes a file-system error briefly.
+     *
+     * @param error - What was thrown
+     * @returns The error's code, such as `ENOENT`, or its message
+     */
+    static showReason(error) {
+        if (error instanceof Error) {
+            const code = error.code;
+            return typeof code === 'string' ? code : error.message;
+        }
+        return String(error);
+    }
+}
+//# sourceMappingURL=corpus-loader.js.map

package/dist/cli/corpus-loader.js.map

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