@rohal12/twee-ts 1.17.0 → 1.17.1

package/dist/index.d.cts

@@ -55,7 +55,10 @@ interface CompileToFileOptions extends CompileOptions {
   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. A build
+   * that changes made while it ran have superseded is neither written nor reported.
+   */
   onBuild?: (result: CompileResult) => void;
   /** Called when a build fails with a fatal error (nothing is written). */
   onError?: (error: Error) => void;
@@ -166,8 +169,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;
 }
@@ -280,7 +285,9 @@ export declare function compileToFile(options: CompileToFileOptions): Promise<Co
 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.
+ * one whose diagnostics report errors. Builds run one at a time: changes made during a
+ * build go into one follow-up build after it, and the superseded build is neither
+ * written nor reported.
  */
 export declare function watch(options: WatchOptions): Promise<AbortController>;
 //#endregion
@@ -305,7 +312,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,7 +356,9 @@ 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
@@ -415,7 +425,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>;
 /**
@@ -499,7 +510,10 @@ export declare function semverCompare(a: [number, number, number], b: [number, n
 //#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.

package/dist/index.d.ts

@@ -55,7 +55,10 @@ interface CompileToFileOptions extends CompileOptions {
   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. A build
+   * that changes made while it ran have superseded is neither written nor reported.
+   */
   onBuild?: (result: CompileResult) => void;
   /** Called when a build fails with a fatal error (nothing is written). */
   onError?: (error: Error) => void;
@@ -166,8 +169,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;
 }
@@ -280,7 +285,9 @@ export declare function compileToFile(options: CompileToFileOptions): Promise<Co
 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.
+ * one whose diagnostics report errors. Builds run one at a time: changes made during a
+ * build go into one follow-up build after it, and the superseded build is neither
+ * written nor reported.
  */
 export declare function watch(options: WatchOptions): Promise<AbortController>;
 //#endregion
@@ -305,7 +312,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,7 +356,9 @@ 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
@@ -415,7 +425,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>;
 /**
@@ -499,7 +510,10 @@ export declare function semverCompare(a: [number, number, number], b: [number, n
 //#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.