@rohal12/twee-ts 1.17.0 → 1.18.0

package/dist/index.d.cts

@@ -10,13 +10,17 @@ type InlineSource = {
 };
 type SourceInput = string | InlineSource;
 interface CompileOptions {
-  /** Files, directories, or inline sources to compile. */
-  sources: SourceInput[];
+  /**
+   * Files, directories, or inline sources to compile. Directories are walked
+   * recursively; inside one, a symbolic link to a file is read, but a link to a
+   * directory is not followed (as in Tweego).
+   */
+  sources: readonly SourceInput[];
   /**
    * Glob patterns for files to leave out of `sources`, matched against each file's
    * path relative to the working directory (as `stats.files` lists it). Modules are not affected.
    */
-  exclude?: string[];
+  exclude?: readonly string[];
   /** Output mode. Default: 'html'. */
   outputMode?: OutputMode;
   /** Story format directory ID (e.g. 'sugarcube-2'). */
@@ -24,11 +28,11 @@ interface CompileOptions {
   /** Name of the starting passage. Default: 'Start'. */
   startPassage?: string;
   /** Extra directories to search for story formats. */
-  formatPaths?: string[];
+  formatPaths?: readonly string[];
   /** Also search TWEEGO_PATH env for formats. Default: true. */
   useTweegoPath?: boolean;
   /** Module files to inject into <head>. */
-  modules?: string[];
+  modules?: readonly string[];
   /** Raw HTML file to append to <head>. */
   headFile?: string;
   /** Trim passage whitespace. Default: true. */
@@ -38,11 +42,24 @@ interface CompileOptions {
   /** Enable debug/test mode option. Default: false. */
   testMode?: boolean;
   /** URLs to SFA-compatible index.json files for remote format lookup. */
-  formatIndices?: string[];
-  /** Direct URLs to format.js files. */
-  formatUrls?: string[];
+  formatIndices?: readonly string[];
+  /**
+   * Direct URLs to format.js files. Each URL's download is cached under that URL, and is
+   * looked up before the downloads shared by name and version.
+   */
+  formatUrls?: readonly string[];
   /** Disable remote format fetching. Default: false. */
   noRemote?: boolean;
+  /**
+   * Cancels the compile. Story format requests still in progress are aborted, and the compile
+   * rejects with the signal's reason. `watch()` aborts its builds, and stops watching, when it aborts.
+   */
+  signal?: AbortSignal;
+  /**
+   * Milliseconds each story format request (an index or a format.js) may take before it fails
+   * with a warning and the next source is tried. 0 turns the limit off. Default: 30000.
+   */
+  formatFetchTimeout?: number;
   /** Map alias tags to canonical special tags (e.g. { library: 'script' }). */
   tagAliases?: Record<string, string>;
   /** Emit source file and line as data- attributes on passage elements. Default: false. */
@@ -51,13 +68,25 @@ interface CompileOptions {
   wordCountMethod?: WordCountMethod;
 }
 interface CompileToFileOptions extends CompileOptions {
-  /** Output file path. */
+  /**
+   * Output file path. It is never read as a source, even inside a source folder or
+   * reached through a symbolic link. Naming it as a source, a module or the head
+   * file is a TweeTsError, and nothing is written.
+   */
   outFile: string;
 }
 interface WatchOptions extends CompileToFileOptions {
-  /** Called after each build is written, including one whose diagnostics report errors. */
+  /**
+   * Called after each build is written, including one whose diagnostics report errors. Builds
+   * run one at a time and are reported in order, each as it finishes, also while changes keep
+   * arriving: the changes made during a build go into one follow-up build after it.
+   */
   onBuild?: (result: CompileResult) => void;
-  /** Called when a build fails with a fatal error (nothing is written). */
+  /**
+   * Called when a build fails with a fatal error (nothing is written), when `onBuild` throws,
+   * and when a watched path can't be watched (the other paths are still watched). An exception
+   * thrown here is reported to the console, and watching goes on.
+   */
   onError?: (error: Error) => void;
 }
 type Diagnostic = {
@@ -166,8 +195,10 @@ interface InspectOptions {
    * Check link destinations against this output's passage rules. A link to a passage that the
    * output leaves out (in Twine 2: `script`, `stylesheet` and `Twine.private` passages,
    * StoryData, StoryTitle and an empty StorySettings; in Twine 1: `Twine.private` passages) is
-   * then a broken link, and says why. Without a target, a link is broken only when no passage
-   * has its name.
+   * then a broken link, and says why. The passages it leaves out also give no links, as their
+   * text never reaches the player, except script passages, which Twine 2 output runs. Without a
+   * target, every source passage gives links, and a link is broken only when no passage has its
+   * name.
    */
   readonly target?: PassageOutputTarget;
 }
@@ -222,6 +253,13 @@ interface SFAIndex {
   twine1: SFAIndexEntry[];
   twine2: SFAIndexEntry[];
 }
+/** Options for the network requests that fetch story formats and their indices. */
+interface RemoteFetchOptions {
+  /** Aborts the requests; the call then rejects with the signal's reason. */
+  readonly signal?: AbortSignal;
+  /** Milliseconds each request may take before it fails. 0 turns the limit off. Default: 30000. */
+  readonly timeout?: number;
+}
 interface FileCacheEntry {
   readonly mtimeMs: number;
   /**
@@ -250,6 +288,8 @@ interface TweeTsConfig {
   twee2Compat?: boolean;
   testMode?: boolean;
   noRemote?: boolean;
+  /** Milliseconds each story format request may take. 0 turns the limit off. Default: 30000. */
+  formatFetchTimeout?: number;
   tagAliases?: Record<string, string>;
   sourceInfo?: boolean;
   wordCountMethod?: WordCountMethod;
@@ -265,7 +305,8 @@ export declare class TweeTsError extends Error {
  */
 export declare function compile(options: CompileOptions): Promise<CompileResult>;
 /**
- * Compile and write to a file.
+ * Compile and write to a file. The file is replaced atomically: a reader sees the previous
+ * build or the new one, never part of it, and a failed write leaves the previous build.
  */
 export declare function compileToFile(options: CompileToFileOptions): Promise<CompileResult>;
 /**
@@ -273,14 +314,22 @@ export declare function compileToFile(options: CompileToFileOptions): Promise<Co
  * Plugins and advanced users can manage their own cache and changed-file tracking.
  *
  * Without `changedFiles`, a cached file is reused while its modification time is unchanged.
- * With it, a file it names (by the path source discovery gives it, relative to the working
- * directory) is always reparsed, whatever its modification time, and every other cached
- * file is reused as it is.
+ * With it, a file it names is always reparsed, whatever its modification time, and every
+ * other cached file is reused as it is. A file may be named by an absolute path or by a path
+ * relative to the working directory, with or without a leading `./`: entries are matched to
+ * the source files by resolved path. A file that fails to load is dropped from the cache, so
+ * the next build tries it again.
  */
 export declare function compileIncremental(options: CompileOptions, cache: Map<string, FileCacheEntry>, changedFiles?: ReadonlySet<string>): Promise<CompileResult>;
 /**
- * Watch for file changes and recompile. Every build is written to `outFile`, including
- * one whose diagnostics report errors.
+ * Watch for file changes and recompile. Every build is written to `outFile` (replacing it
+ * atomically, as compileToFile() does), including one whose diagnostics report errors.
+ * Builds run one at a time, and each one is written and reported as it finishes, in order:
+ * changes made during a build go into one follow-up build after it. A watched path that
+ * can't be watched is passed to `onError`.
+ *
+ * Aborting the returned controller, or the `signal` in the options, stops watching and
+ * aborts the story format requests of the build in progress.
  */
 export declare function watch(options: WatchOptions): Promise<AbortController>;
 //#endregion
@@ -294,9 +343,9 @@ interface StoryMap {
   infoPassages: string[];
   /** All unique tags used across the story, sorted alphabetically. */
   tags: string[];
-  /** Map of tag → passage names that carry that tag. */
+  /** Map of tag → passage names that carry that tag, each listed once even if the tag is repeated. */
   passagesByTag: Map<string, string[]>;
-  /** Map of passage name → tags on that passage. */
+  /** Map of passage name → tags on that passage, as written (a repeated tag appears twice). */
   tagsByPassage: Map<string, string[]>;
   /**
    * Map of passage name → passage names it links to.
@@ -305,7 +354,8 @@ interface StoryMap {
    * `<<goto "target">>` / `<<link "display" "target">>`, read as SugarCube 2 reads them
    * (see `sugarcube-macros.ts`). Links and calls in comments are not read. A script passage is
    * read for links only in its strings; a stylesheet passage (including a loaded `.css` file) is
-   * CSS and links to nothing.
+   * CSS and links to nothing. With a `target` (see `InspectOptions`), a passage that output leaves
+   * out links to nothing, except a script passage, which Twine 2 output runs.
    */
   links: Map<string, string[]>;
   /**
@@ -348,14 +398,18 @@ interface BrokenLink {
  * By default, a link is broken only when no passage has its name. Pass a `target` to check links
  * against what that output emits: `storyInspect(result.story, { target: 'twine2' })` also reports
  * links to passages Twine 2 output leaves out, such as script, stylesheet and `Twine.private`
- * passages.
+ * passages. With a target, passages that output leaves out also give no links (script passages
+ * excepted, as Twine 2 output runs them), so they report no broken links and keep no passage from
+ * being an orphan.
  */
 export declare function storyInspect(story: ReadonlyStory, options?: InspectOptions): StoryMap;
 //#endregion
 //#region src/story.d.ts
 /**
  * Builder that separates the mutable construction phase from the immutable consumption phase.
- * During construction, the internal `Story` is mutable via `add()` and direct access.
+ * During construction, the internal `Story` is mutable via `add()` and direct access: you may
+ * push, splice, sort, rename or reassign `story.passages` between calls, and `add()` and `has()`
+ * see the passages as they are then.
  * After `build()`, the story is returned as `ReadonlyStory`.
  */
 export declare class StoryBuilder {
@@ -378,6 +432,8 @@ interface DecompileResult {
 /**
  * Parse a Twine 2 or Twine 1 compiled HTML file back into a Story model.
  * Tweego always trims passage text; here `trim: false` keeps it exactly, as for Twee sources.
+ * A missing or invalid `tw-storydata` IFID is reported as a warning; an invalid one is kept as
+ * written (uppercased), a missing one stays empty.
  */
 export declare function decompileHTML(html: string, options?: DecompileOptions): DecompileResult;
 //#endregion
@@ -415,7 +471,8 @@ interface LintResult {
  * Uses JSON output mode internally to avoid format resolution, so it checks
  * the starting passage itself, against the Twine 2 passage rules. Link
  * destinations are checked against the same rules: a link to a passage that
- * Twine 2 output leaves out is broken.
+ * Twine 2 output leaves out is broken, and a passage it leaves out (other than
+ * a script passage) gives no links.
  */
 export declare function lint(options: Omit<CompileOptions, 'outputMode'>): Promise<LintResult>;
 /**
@@ -467,39 +524,49 @@ interface ParseResult {
  * Parse Twee source text into passages.
  *
  * The source is normalized first, as files are when they are read: a leading UTF-8 BOM is
- * removed and CRLF and bare CR line endings become LF.
+ * removed and CRLF and bare CR line endings become LF. A BOM at the start of a later line,
+ * directly before `::` (left there by concatenating files), is removed too, so that line
+ * stays a passage header.
  */
 export declare function parseTwee(source: string, options?: ParseOptions): ParseResult;
 //#endregion
 //#region src/formats.d.ts
 /**
- * Parse the Twine 2 format.js JSON chunk.
- * Handles Harlowe's malformed JSON by stripping the "setup" function property. The workaround
- * keys on the property itself, so the same bytes parse whether they come from a `harlowe-3`
- * directory or a direct download.
- * Per spec, the name key is Optional.
+ * Parse the Twine 2 format.js JSON chunk; null when it cannot be used ({@link decodeFormatJSON}
+ * gives the reason).
  *
  * @param _formatId No longer used; kept so existing callers keep compiling.
  */
 export declare function parseFormatJSON(source: string, _formatId?: string): Twine2FormatJSON | null;
 /**
- * Discover all story formats in the given search directories.
- * Implements SemVer-based version pruning: within each (name, major) group,
- * only the highest minor.patch survives.
+ * Discover all story formats in the given search directories, pruned by SemVer: within each
+ * (name, major) group only the highest version survives. See {@link discoverAllFormats} for the
+ * directory ranking and {@link pruneFormats} for pruning.
+ */
+export declare function discoverFormats(searchDirs: readonly string[]): Map<string, StoryFormatInfo>;
+/**
+ * Get the format search directories, lowest rank first: the story format subdirectories of the
+ * home directory, then of the working directory, then each `TWEEGO_PATH` entry, then `extraPaths`
+ * (`formatPaths`). A later directory outranks an earlier one for the same format folder name, so
+ * `formatPaths` override `TWEEGO_PATH`, which overrides the home and working directories, as in
+ * Tweego.
  */
-export declare function discoverFormats(searchDirs: string[]): Map<string, StoryFormatInfo>;
+export declare function getFormatSearchDirs(extraPaths?: readonly string[], useTweegoPath?: boolean): string[];
 /**
- * Get the default format search directories.
+ * Parse a version string into [major, minor, patch]. Accepts what {@link parseVersion} accepts
+ * (`v1.2.3`, `1.2`, `2.0.0-beta.1`); the prerelease and build metadata are dropped.
  */
-export declare function getFormatSearchDirs(extraPaths?: string[], useTweegoPath?: boolean): string[];
-/** Parse a simple semver string into [major, minor, patch]. */
 export declare function parseSemver(v: string): [number, number, number] | null;
+/** Compare [major, minor, patch] tuples. Use {@link compareVersions} to take prereleases into account. */
 export declare function semverCompare(a: [number, number, number], b: [number, number, number]): number;
 //#endregion
 //#region src/ifid.d.ts
 /** Generate a new IFID (UUID v4, uppercase). */
 export declare function generateIFID(): IFID;
-/** Validate and brand an IFID string. Throws on invalid input. */
+/**
+ * Validate and brand an IFID string. Throws on invalid input.
+ * Returns the IFID in its stored form (see `normalizeIFID`).
+ */
 export declare function createIFID(value: string): IFID;
 /**
  * Validate an IFID string.
@@ -510,31 +577,63 @@ export declare function validateIFID(ifid: string): string | null;
 //#endregion
 //#region src/config.d.ts
 export declare const CONFIG_FILENAME = "twee-ts.config.json";
-/** Load a config file from the given directory (default: cwd). Returns null if not found. */
-export declare function loadConfig(dir?: string): TweeTsConfig | null;
-/** Load a config from a specific file path. */
-export declare function loadConfigFile(filePath: string): TweeTsConfig;
-/** Validate a config object. Returns an array of error strings (empty = valid). */
+/**
+ * Load a config file from the given directory (default: cwd). Returns null if not found.
+ *
+ * @param diagnostics Receives warnings that do not stop the config from loading: keys the config does not
+ *   define, and a file that is not valid UTF-8 (it is read as Windows-1252).
+ * @throws When the file is not valid JSON or fails {@link validateConfig}.
+ */
+export declare function loadConfig(dir?: string, diagnostics?: Diagnostic[]): TweeTsConfig | null;
+/**
+ * Load a config from a specific file path.
+ *
+ * @param diagnostics Receives warnings that do not stop the config from loading: keys the config does not
+ *   define, and a file that is not valid UTF-8 (it is read as Windows-1252).
+ * @throws When the file cannot be read, is not valid JSON or fails {@link validateConfig}.
+ */
+export declare function loadConfigFile(filePath: string, diagnostics?: Diagnostic[]): TweeTsConfig;
+/**
+ * Validate a config object. Returns an array of error strings (empty = valid).
+ * Keys the config does not define are not errors; {@link unknownConfigKeyWarnings} reports them.
+ */
 export declare function validateConfig(data: unknown): string[];
+/**
+ * Warnings for the keys of a config object that the config does not define (the JSON schema's
+ * `additionalProperties: false`), other than `$schema`. twee-ts ignores such a key, so a misspelt one would
+ * otherwise leave its option at the default without a word. A key that differs from a defined one only in
+ * letter case, `-` or `_` (`formatID`, `output-mode`) gets a suggestion. Returns `[]` for anything that is not
+ * an object, which {@link validateConfig} reports.
+ */
+export declare function unknownConfigKeyWarnings(data: unknown): string[];
 /** Return a default config JSON string for --init scaffolding. */
 export declare function scaffoldConfig(): string;
 //#endregion
 //#region src/remote-formats.d.ts
 /** Get the cache directory for downloaded story formats. */
 export declare function getCacheDir(): string;
-/** Download a format, verify its checksum, write to cache, and return StoryFormatInfo. */
-export declare function fetchAndCacheFormat(entry: SFAIndexEntry, downloadUrl: string): Promise<StoryFormatInfo>;
-/** Download a direct format.js URL, parse its JSON, cache it, and return StoryFormatInfo. */
-export declare function fetchDirectFormat(url: string): Promise<StoryFormatInfo>;
+/**
+ * Download a format, verify its checksum, write it to the cache shared by name and version, and
+ * return its StoryFormatInfo. Concurrent calls for one download URL share one request.
+ */
+export declare function fetchAndCacheFormat(entry: SFAIndexEntry, downloadUrl: string, options?: RemoteFetchOptions): Promise<StoryFormatInfo>;
+/**
+ * Download a direct format.js URL, parse its JSON, cache it under that URL (apart from the
+ * downloads shared by name and version), and return its StoryFormatInfo. Concurrent calls for
+ * one URL share one request.
+ */
+export declare function fetchDirectFormat(url: string, options?: RemoteFetchOptions): Promise<StoryFormatInfo>;
 /**
  * Try to resolve a remote story format by name and version.
- * 0. Use an exactly matching cached download, without touching the network
- * 1. Try direct format URLs
- * 2. Try custom index URLs
- * 3. Try default SFA indices
- * 4. Fall back to a compatible cached download (e.g. when offline)
+ * 1. Try direct format URLs (each one's cached copy, else a download)
+ * 2. Use an exactly matching download from the shared cache, without touching the network
+ * 3. Try custom index URLs, then the default SFA indices
+ * 4. Fall back to a compatible download from the shared cache (e.g. when offline)
+ *
+ * `options.signal` aborts the lookup, which then rejects with the signal's reason;
+ * `options.timeout` limits each request (default {@link DEFAULT_FORMAT_FETCH_TIMEOUT} ms).
  */
-export declare function resolveRemoteFormat(name: string, version: string, indices?: string[], urls?: string[]): Promise<StoryFormatInfo | undefined>;
+export declare function resolveRemoteFormat(name: string, version: string, indices?: readonly string[], urls?: readonly string[], options?: RemoteFetchOptions): Promise<StoryFormatInfo | undefined>;
 /** Discover all cached remote formats. Returns a Map like discoverFormats(). */
 export declare function discoverCachedFormats(): Map<string, StoryFormatInfo>;
 /** Info about a cached format entry with size and modification date. */
@@ -548,6 +647,8 @@ interface CachedFormatEntry {
 export declare function listCachedFormats(): readonly CachedFormatEntry[];
 /**
  * Clear all cached formats, or only those matching a given name. Returns the number of entries removed.
+ * Clearing all also removes the downloads from direct format URLs; a name clears only the
+ * downloads shared by name and version.
  * A name must be a single cache entry name (as `listCachedFormats()` reports it); anything with a
  * path separator or `.`/`..` throws instead of deleting outside the format's own directory.
  */
@@ -558,4 +659,4 @@ export declare function getCacheSize(): {
   count: number;
 };
 //#endregion
-export type { BrokenLink, CachedFormatEntry, CompileOptions, CompileResult, CompileStats, CompileToFileOptions, DecompileOptions, DecompileResult, Diagnostic, FileCacheEntry, IFID, InlineSource, InspectOptions, LexerItem, LintResult, OmittingTag, OutputMode, Passage, PassageMetadata, PassageOmission, PassageOutputTarget, ReadonlyPassage, ReadonlyStory, SFAIndex, SFAIndexEntry, SourceInput, SourceLocation, Story, StoryFormatInfo, StoryMap, TweeTsConfig, WatchOptions, WordCountMethod };
+export type { BrokenLink, CachedFormatEntry, CompileOptions, CompileResult, CompileStats, CompileToFileOptions, DecompileOptions, DecompileResult, Diagnostic, FileCacheEntry, IFID, InlineSource, InspectOptions, LexerItem, LintResult, OmittingTag, OutputMode, Passage, PassageMetadata, PassageOmission, PassageOutputTarget, ReadonlyPassage, ReadonlyStory, RemoteFetchOptions, SFAIndex, SFAIndexEntry, SourceInput, SourceLocation, Story, StoryFormatInfo, StoryMap, TweeTsConfig, WatchOptions, WordCountMethod };