@rohal12/twee-ts 1.16.0 → 1.17.0

package/dist/index.d.cts

@@ -55,9 +55,9 @@ interface CompileToFileOptions extends CompileOptions {
   outFile: string;
 }
 interface WatchOptions extends CompileToFileOptions {
-  /** Called after each successful rebuild. */
+  /** Called after each build is written, including one whose diagnostics report errors. */
   onBuild?: (result: CompileResult) => void;
-  /** Called on build errors. */
+  /** Called when a build fails with a fatal error (nothing is written). */
   onError?: (error: Error) => void;
 }
 type Diagnostic = {
@@ -142,6 +142,35 @@ type ReadonlyStory = Readonly<Omit<Story, 'passages' | 'twine1' | 'twine2'>> & {
     readonly tagColors: ReadonlyMap<string, string>;
   };
 };
+type OmittingTag = 'Twine.private' | 'script' | 'stylesheet';
+type PassageOmission = {
+  readonly kind: 'special-name';
+  readonly name: 'StoryData' | 'StoryTitle';
+} | {
+  readonly kind: 'tag';
+  readonly tag: OmittingTag;
+} | {
+  readonly kind: 'empty-story-settings';
+};
+/** The output whose rules decide which passages a story emits as passages. */
+type PassageOutputTarget = 'twine1' | 'twine2';
+interface DecompileOptions {
+  /**
+   * Trim whitespace at both ends of passage text (and of the Twine 2 story stylesheet and script),
+   * as the Twee lexer does. When false, the stored text is kept exactly. Default: true.
+   */
+  readonly trim?: boolean;
+}
+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.
+   */
+  readonly target?: PassageOutputTarget;
+}
 interface StoryFormatInfo {
   id: string;
   filename: string;
@@ -195,6 +224,12 @@ interface SFAIndex {
 }
 interface FileCacheEntry {
   readonly mtimeMs: number;
+  /**
+   * Identity of the parse options (`trim`, `twee2Compat`) the entry was parsed with. An entry is
+   * reused only when this matches the current options; an entry without it is treated as stale
+   * and reparsed. The value is opaque: leave it to twee-ts to set.
+   */
+  readonly parseOptionsKey?: string;
   readonly passages: readonly Passage[];
   readonly diagnostics: readonly Diagnostic[];
 }
@@ -236,10 +271,16 @@ export declare function compileToFile(options: CompileToFileOptions): Promise<Co
 /**
  * Compile with incremental caching support.
  * 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.
  */
 export declare function compileIncremental(options: CompileOptions, cache: Map<string, FileCacheEntry>, changedFiles?: ReadonlySet<string>): Promise<CompileResult>;
 /**
- * Watch for file changes and recompile.
+ * Watch for file changes and recompile. Every build is written to `outFile`, including
+ * one whose diagnostics report errors.
  */
 export declare function watch(options: WatchOptions): Promise<AbortController>;
 //#endregion
@@ -259,12 +300,18 @@ interface StoryMap {
   tagsByPassage: Map<string, string[]>;
   /**
    * Map of passage name → passage names it links to.
-   * Parses `[[target]]`, `[[display->target]]`, `[[display|target]]`,
-   * and SugarCube's `<<goto "target">>` / `<<link "display" "target">>`,
-   * whose arguments are read as SugarCube 2 reads them (see `sugarcube-macros.ts`).
+   * Parses `[[target]]`, `[[display->target]]`, `[[target<-display]]`, `[[display|target]]`,
+   * each with or without a setter (`[[display|target][$x to 1]]`), and SugarCube's
+   * `<<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.
    */
   links: Map<string, string[]>;
-  /** Broken links: `{ from, to }` pairs where `to` doesn't exist as a passage. */
+  /**
+   * Broken links: `{ from, to }` pairs where `to` doesn't exist as a passage, or, with a `target`
+   * (see `InspectOptions`), where that output leaves the `to` passage out (`omission` says why).
+   */
   brokenLinks: BrokenLink[];
   /** Story passages with no outgoing links (potential dead ends). */
   deadEnds: string[];
@@ -276,6 +323,11 @@ interface StoryMap {
 interface BrokenLink {
   from: string;
   to: string;
+  /**
+   * Set when a passage named `to` exists, but the inspected output leaves it out of the story
+   * (only with a `target`): why it is left out. Absent when no passage has the name.
+   */
+  omission?: PassageOmission;
 }
 /**
  * Inspect a story and return its full structural map.
@@ -292,8 +344,13 @@ interface BrokenLink {
  * expect(map.brokenLinks).toEqual([]);
  * expect(map.deadEnds).not.toContain('Start');
  * ```
+ *
+ * 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.
  */
-export declare function storyInspect(story: ReadonlyStory): StoryMap;
+export declare function storyInspect(story: ReadonlyStory, options?: InspectOptions): StoryMap;
 //#endregion
 //#region src/story.d.ts
 /**
@@ -320,8 +377,9 @@ 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.
  */
-export declare function decompileHTML(html: string): DecompileResult;
+export declare function decompileHTML(html: string, options?: DecompileOptions): DecompileResult;
 //#endregion
 //#region src/lint.d.ts
 interface LintResult {
@@ -341,7 +399,11 @@ interface LintResult {
   storyPassages: number;
   /** Info/special passage count. */
   infoPassages: number;
-  /** Broken links: link targets that don't exist as passages. */
+  /**
+   * Broken links: link targets that don't exist as passages, or that Twine 2 output leaves out
+   * (script, stylesheet and `Twine.private` passages, StoryData, StoryTitle, an empty
+   * StorySettings); for those, `omission` says why.
+   */
   brokenLinks: BrokenLink[];
   /** Story passages with no outgoing links. */
   deadEnds: string[];
@@ -350,7 +412,10 @@ interface LintResult {
 }
 /**
  * Lint a story: compile without output rendering, then inspect structure.
- * Uses JSON output mode internally to avoid format resolution.
+ * 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.
  */
 export declare function lint(options: Omit<CompileOptions, 'outputMode'>): Promise<LintResult>;
 /**
@@ -400,16 +465,23 @@ 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.
  */
 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.
+ * 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.
+ *
+ * @param _formatId No longer used; kept so existing callers keep compiling.
  */
-export declare function parseFormatJSON(source: string, formatId: string): Twine2FormatJSON | null;
+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,
@@ -456,9 +528,11 @@ export declare function fetchAndCacheFormat(entry: SFAIndexEntry, downloadUrl: s
 export declare function fetchDirectFormat(url: string): 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)
  */
 export declare function resolveRemoteFormat(name: string, version: string, indices?: string[], urls?: string[]): Promise<StoryFormatInfo | undefined>;
 /** Discover all cached remote formats. Returns a Map like discoverFormats(). */
@@ -472,7 +546,11 @@ interface CachedFormatEntry {
 }
 /** List all cached formats with size and modification date. */
 export declare function listCachedFormats(): readonly CachedFormatEntry[];
-/** Clear all cached formats, or only those matching a given name. Returns the number of entries removed. */
+/**
+ * Clear all cached formats, or only those matching a given name. Returns the number of entries removed.
+ * 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.
+ */
 export declare function clearCachedFormats(name?: string): number;
 /** Get total cache size in bytes and format count. */
 export declare function getCacheSize(): {
@@ -480,4 +558,4 @@ export declare function getCacheSize(): {
   count: number;
 };
 //#endregion
-export type { BrokenLink, CachedFormatEntry, CompileOptions, CompileResult, CompileStats, CompileToFileOptions, DecompileResult, Diagnostic, FileCacheEntry, IFID, InlineSource, LexerItem, LintResult, OutputMode, Passage, PassageMetadata, 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, SFAIndex, SFAIndexEntry, SourceInput, SourceLocation, Story, StoryFormatInfo, StoryMap, TweeTsConfig, WatchOptions, WordCountMethod };

package/dist/index.d.ts

@@ -55,9 +55,9 @@ interface CompileToFileOptions extends CompileOptions {
   outFile: string;
 }
 interface WatchOptions extends CompileToFileOptions {
-  /** Called after each successful rebuild. */
+  /** Called after each build is written, including one whose diagnostics report errors. */
   onBuild?: (result: CompileResult) => void;
-  /** Called on build errors. */
+  /** Called when a build fails with a fatal error (nothing is written). */
   onError?: (error: Error) => void;
 }
 type Diagnostic = {
@@ -142,6 +142,35 @@ type ReadonlyStory = Readonly<Omit<Story, 'passages' | 'twine1' | 'twine2'>> & {
     readonly tagColors: ReadonlyMap<string, string>;
   };
 };
+type OmittingTag = 'Twine.private' | 'script' | 'stylesheet';
+type PassageOmission = {
+  readonly kind: 'special-name';
+  readonly name: 'StoryData' | 'StoryTitle';
+} | {
+  readonly kind: 'tag';
+  readonly tag: OmittingTag;
+} | {
+  readonly kind: 'empty-story-settings';
+};
+/** The output whose rules decide which passages a story emits as passages. */
+type PassageOutputTarget = 'twine1' | 'twine2';
+interface DecompileOptions {
+  /**
+   * Trim whitespace at both ends of passage text (and of the Twine 2 story stylesheet and script),
+   * as the Twee lexer does. When false, the stored text is kept exactly. Default: true.
+   */
+  readonly trim?: boolean;
+}
+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.
+   */
+  readonly target?: PassageOutputTarget;
+}
 interface StoryFormatInfo {
   id: string;
   filename: string;
@@ -195,6 +224,12 @@ interface SFAIndex {
 }
 interface FileCacheEntry {
   readonly mtimeMs: number;
+  /**
+   * Identity of the parse options (`trim`, `twee2Compat`) the entry was parsed with. An entry is
+   * reused only when this matches the current options; an entry without it is treated as stale
+   * and reparsed. The value is opaque: leave it to twee-ts to set.
+   */
+  readonly parseOptionsKey?: string;
   readonly passages: readonly Passage[];
   readonly diagnostics: readonly Diagnostic[];
 }
@@ -236,10 +271,16 @@ export declare function compileToFile(options: CompileToFileOptions): Promise<Co
 /**
  * Compile with incremental caching support.
  * 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.
  */
 export declare function compileIncremental(options: CompileOptions, cache: Map<string, FileCacheEntry>, changedFiles?: ReadonlySet<string>): Promise<CompileResult>;
 /**
- * Watch for file changes and recompile.
+ * Watch for file changes and recompile. Every build is written to `outFile`, including
+ * one whose diagnostics report errors.
  */
 export declare function watch(options: WatchOptions): Promise<AbortController>;
 //#endregion
@@ -259,12 +300,18 @@ interface StoryMap {
   tagsByPassage: Map<string, string[]>;
   /**
    * Map of passage name → passage names it links to.
-   * Parses `[[target]]`, `[[display->target]]`, `[[display|target]]`,
-   * and SugarCube's `<<goto "target">>` / `<<link "display" "target">>`,
-   * whose arguments are read as SugarCube 2 reads them (see `sugarcube-macros.ts`).
+   * Parses `[[target]]`, `[[display->target]]`, `[[target<-display]]`, `[[display|target]]`,
+   * each with or without a setter (`[[display|target][$x to 1]]`), and SugarCube's
+   * `<<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.
    */
   links: Map<string, string[]>;
-  /** Broken links: `{ from, to }` pairs where `to` doesn't exist as a passage. */
+  /**
+   * Broken links: `{ from, to }` pairs where `to` doesn't exist as a passage, or, with a `target`
+   * (see `InspectOptions`), where that output leaves the `to` passage out (`omission` says why).
+   */
   brokenLinks: BrokenLink[];
   /** Story passages with no outgoing links (potential dead ends). */
   deadEnds: string[];
@@ -276,6 +323,11 @@ interface StoryMap {
 interface BrokenLink {
   from: string;
   to: string;
+  /**
+   * Set when a passage named `to` exists, but the inspected output leaves it out of the story
+   * (only with a `target`): why it is left out. Absent when no passage has the name.
+   */
+  omission?: PassageOmission;
 }
 /**
  * Inspect a story and return its full structural map.
@@ -292,8 +344,13 @@ interface BrokenLink {
  * expect(map.brokenLinks).toEqual([]);
  * expect(map.deadEnds).not.toContain('Start');
  * ```
+ *
+ * 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.
  */
-export declare function storyInspect(story: ReadonlyStory): StoryMap;
+export declare function storyInspect(story: ReadonlyStory, options?: InspectOptions): StoryMap;
 //#endregion
 //#region src/story.d.ts
 /**
@@ -320,8 +377,9 @@ 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.
  */
-export declare function decompileHTML(html: string): DecompileResult;
+export declare function decompileHTML(html: string, options?: DecompileOptions): DecompileResult;
 //#endregion
 //#region src/lint.d.ts
 interface LintResult {
@@ -341,7 +399,11 @@ interface LintResult {
   storyPassages: number;
   /** Info/special passage count. */
   infoPassages: number;
-  /** Broken links: link targets that don't exist as passages. */
+  /**
+   * Broken links: link targets that don't exist as passages, or that Twine 2 output leaves out
+   * (script, stylesheet and `Twine.private` passages, StoryData, StoryTitle, an empty
+   * StorySettings); for those, `omission` says why.
+   */
   brokenLinks: BrokenLink[];
   /** Story passages with no outgoing links. */
   deadEnds: string[];
@@ -350,7 +412,10 @@ interface LintResult {
 }
 /**
  * Lint a story: compile without output rendering, then inspect structure.
- * Uses JSON output mode internally to avoid format resolution.
+ * 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.
  */
 export declare function lint(options: Omit<CompileOptions, 'outputMode'>): Promise<LintResult>;
 /**
@@ -400,16 +465,23 @@ 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.
  */
 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.
+ * 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.
+ *
+ * @param _formatId No longer used; kept so existing callers keep compiling.
  */
-export declare function parseFormatJSON(source: string, formatId: string): Twine2FormatJSON | null;
+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,
@@ -456,9 +528,11 @@ export declare function fetchAndCacheFormat(entry: SFAIndexEntry, downloadUrl: s
 export declare function fetchDirectFormat(url: string): 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)
  */
 export declare function resolveRemoteFormat(name: string, version: string, indices?: string[], urls?: string[]): Promise<StoryFormatInfo | undefined>;
 /** Discover all cached remote formats. Returns a Map like discoverFormats(). */
@@ -472,7 +546,11 @@ interface CachedFormatEntry {
 }
 /** List all cached formats with size and modification date. */
 export declare function listCachedFormats(): readonly CachedFormatEntry[];
-/** Clear all cached formats, or only those matching a given name. Returns the number of entries removed. */
+/**
+ * Clear all cached formats, or only those matching a given name. Returns the number of entries removed.
+ * 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.
+ */
 export declare function clearCachedFormats(name?: string): number;
 /** Get total cache size in bytes and format count. */
 export declare function getCacheSize(): {
@@ -480,4 +558,4 @@ export declare function getCacheSize(): {
   count: number;
 };
 //#endregion
-export type { BrokenLink, CachedFormatEntry, CompileOptions, CompileResult, CompileStats, CompileToFileOptions, DecompileResult, Diagnostic, FileCacheEntry, IFID, InlineSource, LexerItem, LintResult, OutputMode, Passage, PassageMetadata, 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, SFAIndex, SFAIndexEntry, SourceInput, SourceLocation, Story, StoryFormatInfo, StoryMap, TweeTsConfig, WatchOptions, WordCountMethod };