Reviewing documentation of internal and published modules

common/reviews/api/archivable.api.md

@@ -4,111 +4,143 @@
 
 ```ts
 
+// Warning: (ae-forgotten-export) The symbol "IArchivable" needs to be exported by the entry point index.d.ts
+//
 // @public
-class Archivable implements IArchivable {
-    constructor(url: string, selector?: string, truncate?: string);
-    // (undocumented)
-    readonly archive: string | null;
-    static fromJSON(maybeValidString: string): Archivable;
-    static fromLine(line?: string): Archivable;
-    // (undocumented)
-    static fromTuple(tuple: IArchivableOrderedInputUrlTruncateTuple): Archivable;
-    static parseLine(line?: string): IArchivableOrderedInputUrlTruncateTuple;
-    // (undocumented)
-    readonly selector: string;
-    // (undocumented)
-    toJSON(): Readonly<IArchivable>;
-    // (undocumented)
-    toTuple(): Readonly<IArchivableOrderedInputUrlTruncateTuple>;
-    // (undocumented)
-    readonly truncate: string;
-    // (undocumented)
-    readonly url: string;
+class Archivable implements IArchivable_2 {
+  constructor(url: string, selector?: string, truncate?: string)
+  // (undocumented)
+  readonly archive: string | null
+  static fromJSON(maybeValidString: string): Archivable
+  static fromLine(line?: string): Archivable
+  // Warning: (ae-forgotten-export) The symbol "IArchivableOrderedInputUrlTruncateTuple" needs to be exported by the entry point index.d.ts
+  //
+  // (undocumented)
+  static fromTuple(tuple: IArchivableOrderedInputUrlTruncateTuple_2): Archivable
+  static parseLine(line?: string): IArchivableOrderedInputUrlTruncateTuple_2
+  // (undocumented)
+  readonly selector: string
+  // (undocumented)
+  toJSON(): Readonly<IArchivable_2>
+  // (undocumented)
+  toTuple(): Readonly<IArchivableOrderedInputUrlTruncateTuple_2>
+  // (undocumented)
+  readonly truncate: string
+  // (undocumented)
+  readonly url: string
 }
 
 export { Archivable }
 
 export default Archivable;
 
 // @public
-export const ArchivableOrderedInputUrlTruncateTuplesFirstLine = "\"Web Page URL\";\"CSS Selectors for main content\";\"CSS Selectors to strip content off\"";
+export const ArchivableOrderedInputUrlTruncateTuplesFirstLine =
+  '"Web Page URL";"CSS Selectors for main content";"CSS Selectors to strip content off"';
+
+// Warning: (ae-incompatible-release-tags) The symbol "assetFileExtensionNormalizer" is marked as @public, but its signature references "INormalizedAssetFileExtensionExtractorFn" which is marked as @internal
+//
+// @public
+export const assetFileExtensionNormalizer: INormalizedAssetFileExtensionExtractorFn;
 
 // @public
-export type CryptoCommonHashingFunctions = 'sha1' | 'sha256' | 'md5' | 'md5-sha1' | 'mdc2' | 'sha512' | 'sha224' | string;
+export const assetUrlNormalizer: (sourceDocument: string, asset: string) => string;
+
+// @public
+export type CryptoCommonHashingFunctions =
+  | 'sha1'
+  | 'sha256'
+  | 'md5'
+  | 'md5-sha1'
+  | 'mdc2'
+  | 'sha512'
+  | 'sha224'
+  | string
 
 // @public
 export class DocumentAssets implements Iterable<INormalizedAsset> {
-    [Symbol.iterator](): Iterator<INormalizedAsset>;
-    constructor(sourceDocument: string, assets?: string[]);
-    next(): IteratorResult<Readonly<INormalizedAsset>>;
-    // Warning: (ae-incompatible-release-tags) The symbol "setReferenceHandler" is marked as @public, but its signature references "INormalizedAssetReferenceHandlerFn" which is marked as @internal
-    setReferenceHandler(handler: INormalizedAssetReferenceHandlerFn): void;
-    // (undocumented)
-    readonly sourceDocument: string;
+  [Symbol.iterator](): Iterator<INormalizedAsset>
+  constructor(sourceDocument: string, assets?: string[])
+  next(): IteratorResult<Readonly<INormalizedAsset>>
+  // Warning: (ae-incompatible-release-tags) The symbol "setReferenceHandler" is marked as @public, but its signature references "INormalizedAssetReferenceHandlerFn" which is marked as @internal
+  setReferenceHandler(handler: INormalizedAssetReferenceHandlerFn): void
+  // (undocumented)
+  readonly sourceDocument: string
 }
 
 // @public
 export interface IArchivable {
-    archive: string | null;
-    selector: string;
-    truncate: string;
-    url: string;
+  archive: string | null
+  selector: string
+  truncate: string
+  url: string
 }
 
 // @public
-export type IArchivableOrderedInputUrlTruncateTuple = [string, string, string];
+export type IArchivableOrderedInputUrlTruncateTuple = [
+  string,
+  string,
+  string,
+]
 
 // Warning: (ae-internal-missing-underscore) The name "IHashingFn" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal
-export type IHashingFn = (message: string) => string;
+export type IHashingFn = (message: string) => string
 
 // @public
 export interface INormalizedAsset {
-    dest: string | null;
-    readonly match: string;
-    reference: string | null;
-    readonly src: string;
+  dest: string | null
+  readonly match: string
+  reference: string | null
+  readonly src: string
 }
 
 // @public
 export interface INormalizedAssetDest {
-    // (undocumented)
-    dest: string;
+  // (undocumented)
+  dest: string
 }
 
 // Warning: (ae-internal-missing-underscore) The name "INormalizedAssetEntity" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal
 export interface INormalizedAssetEntity {
-    // (undocumented)
-    toJSON(): Readonly<INormalizedAsset>;
+  // (undocumented)
+  toJSON(): Readonly<INormalizedAsset>
 }
 
 // Warning: (ae-internal-missing-underscore) The name "INormalizedAssetFileExtensionExtractorFn" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal
-export type INormalizedAssetFileExtensionExtractorFn = (assetUrl: string) => string;
+export type INormalizedAssetFileExtensionExtractorFn = (
+  assetUrl: string,
+) => string
 
 // Warning: (ae-internal-missing-underscore) The name "INormalizedAssetReference" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal
 export interface INormalizedAssetReference {
-    // (undocumented)
-    hasExtension: boolean;
-    // (undocumented)
-    reference: string;
+  // (undocumented)
+  hasExtension: boolean
+  // (undocumented)
+  reference: string
 }
 
 // Warning: (ae-internal-missing-underscore) The name "INormalizedAssetReferenceHandlerFactoryFn" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal
-export type INormalizedAssetReferenceHandlerFactoryFn = (hashingHandler: IHashingFn, extensionHandler: INormalizedAssetFileExtensionExtractorFn) => INormalizedAssetReferenceHandlerFn;
+export type INormalizedAssetReferenceHandlerFactoryFn = (
+  hashingHandler: IHashingFn,
+  extensionHandler: INormalizedAssetFileExtensionExtractorFn,
+) => INormalizedAssetReferenceHandlerFn
 
 // Warning: (ae-internal-missing-underscore) The name "INormalizedAssetReferenceHandlerFn" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal
-export type INormalizedAssetReferenceHandlerFn = (asset: INormalizedAsset) => INormalizedAssetReference;
+export type INormalizedAssetReferenceHandlerFn = (
+  asset: INormalizedAsset,
+) => INormalizedAssetReference
 
 // Warning: (ae-incompatible-release-tags) The symbol "NormalizedAsset" is marked as @public, but its signature references "INormalizedAssetEntity" which is marked as @internal
 //

common/reviews/api/content-divinator.api.md

@@ -24,6 +24,12 @@ export interface ISummaryRecordType {
 // @public
 export type NonStopWordIsserType = (word: string) => boolean;
 
+// @public (undocumented)
+export const utils: {
+    convertMapToRecordHashMap: (textMap: Map<string, number>) => Record<string, number>;
+    convertRecordHashMapToMap: (textHashMap: Record<string, number>) => Map<string, number>;
+};
+
 // @public
 export type WordNormalizerType = (word: any) => string | void;
 

packages/archivable/README.md

@@ -7,7 +7,7 @@ A _Data Transfer Object_ (or _Entity_ object) and related utilities to
 manipulate Web Page Metadata while archiving.
 
 [repo-url]:
-  https://github.com/renoirb/archivator/blob/v3.x-dev/packages/archivable
+  https://github.com/renoirb/archivator/tree/v3.x-dev/packages/archivable
   'Archivable Data Transfer Object'
 [npmjs-package-badge]:
   https://img.shields.io/npm/v/%40archivator%2Farchivable?style=flat-square&logo=appveyor&label=npm&logo=npm
@@ -23,10 +23,17 @@ manipulate Web Page Metadata while archiving.
 
 ## Usage
 
+[api-extractor-review]:
+  https://github.com/renoirb/archivator/blob/v3.x-dev/common/reviews/api/archivable.api.md
+  'API Report'
+[api-extractor-docs]:
+  https://github.com/renoirb/archivator/blob/v3.x-dev/packages/archivable/docs/index.md
+  'API Extractor docs/'
+
 _See also_:
 
-- [API Extractor code-review signature](../../common/reviews/api/archivable.api.md)
-- [API Documentor generated docs](./docs/index.md)
+- [API Extractor code-review signature][api-extractor-review]
+- [API Documentor generated docs][api-extractor-docs]
 
 ### Archivable
 
@@ -208,9 +215,9 @@ at `assetFileExtensionNormalizer`.
 ```ts
 // ... Continuing from example above
 import {
-  HashingFunctionType,
+  IHashingFn,
   createHashFunction,
-  NormalizedAssetFileExtensionExtractorType,
+  INormalizedAssetReferenceHandlerFn,
 } from '@archivator/archivable'
 
 // One can set its own hash function
@@ -221,7 +228,7 @@ const hashingHandler = createHashFunction('md5', 'hex')
  * In the example below, in every case, the file extension would ALWAYS be ".foo".
  * We could eventually use the file's mime-type, or the source's response headers. #TODO
  */
-const extensionHandler: NormalizedAssetFileExtensionExtractorType = (
+const extensionHandler: INormalizedAssetReferenceHandlerFn = (
   foo: string,
 ): string => `.foo`
 

packages/archivable/config/api-extractor.json

@@ -60,7 +60,7 @@
    * This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
    * local files for library1.
    */
-  "bundledPackages": [],
+  "bundledPackages": ["url-dirname-normalizer", "crypto"],
 
   /**
    * Determines how the TypeScript compiler engine will be invoked by API Extractor.
@@ -181,7 +181,7 @@
     /**
      * (REQUIRED) Whether to generate the .d.ts rollup file.
      */
-    "enabled": true
+    "enabled": true,
 
     /**
      * Specifies the output path for a .d.ts rollup file to be generated without any trimming.
@@ -230,7 +230,7 @@
      *
      * DEFAULT VALUE: false
      */
-    // "omitTrimmingComments": true
+    "omitTrimmingComments": true
   },
 
   /**
@@ -266,7 +266,7 @@
    *
    * DEFAULT VALUE: "crlf"
    */
-  // "newlineKind": "crlf",
+  "newlineKind": "lf",
 
   /**
    * Configures how API Extractor reports error and warning messages produced during analysis.

packages/archivable/docs/archivable.archivableorderedinputurltruncatetuplesfirstline.md

@@ -5,18 +5,23 @@
 
 ## ArchivableOrderedInputUrlTruncateTuplesFirstLine variable
 
-The first line of the archive index CSV file.
-
-1. First item is a fully qualified source document URL (i.e. a Web Page's
-   address) 2. \_selector\_, A CSS selector where the main content is 3.
-   \_truncate\_, A list of CSS selectors to strip off (e.g. ads, orthogonal
-   content)
-
-This is the shape of data input we can use for iteration.
+Tuple representation of what comes from a source .csv file
 
 <b>Signature:</b>
 
 ```typescript
 ArchivableOrderedInputUrlTruncateTuplesFirstLine =
   '"Web Page URL";"CSS Selectors for main content";"CSS Selectors to strip content off"'
 ```
+
+## Remarks
+
+Given every row in source file .csv, e.g.
+"http://example.org/a/b.html;body;.ad,.social-button"
+
+1. First item is a fully qualified source document URL (i.e. a Web Page's
+   address) 2. \_selector\_, A CSS selector where the main content is 3.
+   \_truncate\_, A list of CSS selectors to strip off (e.g. ads, orthogonal
+   content)
+
+This is the shape of data input we can use for iteration.

packages/archivable/docs/archivable.assetfileextensionnormalizer.md

@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@archivator/archivable](./archivable.md) &gt;
+[assetFileExtensionNormalizer](./archivable.assetfileextensionnormalizer.md)
+
+## assetFileExtensionNormalizer variable
+
+Return a file extension with a dot as prefix, or an empty string.
+
+One can set their own normalizer, as long as it of type
+`(file: string) => string` When the output is either an empty string, or a file
+extension prefixed by a dot (e.g. `.png`<!-- -->)
+
+<b>Signature:</b>
+
+```typescript
+assetFileExtensionNormalizer: INormalizedAssetFileExtensionExtractorFn
+```

packages/archivable/docs/archivable.asseturlnormalizer.md

@@ -0,0 +1,47 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@archivator/archivable](./archivable.md) &gt;
+[assetUrlNormalizer](./archivable.asseturlnormalizer.md)
+
+## assetUrlNormalizer variable
+
+Normalize Asset Reference.
+
+Given we have an article URL at `http://example.org/foo/bar/baz.html` (a.k.a.
+"`sourceDocument`<!-- -->") where we can have many image tags we want to keep a
+copy (e.g. `<img src="/image/a.jpg" />`<!-- -->, refered here as
+"`asset`<!-- -->"). We want to know where should we download `/image/a.jpg`
+from. To do this, we can figure out by combining the `sourceDocument` and the
+`asset`
+
+For a given `sourceDocument` URL with 0 or more assets in document's HTML, we
+want to get output as:
+
+```json
+[ 'http://example.org/image/a.jpg', ... ]
+
+```
+
+This module should handle all valid asset paths and return a fully qualified URL
+so we can download the asset.
+
+For example, the URL of a sourceDocument could be
+"http://example.org/foo/bar.html" with images ("asset" img tags with src="...")
+img\[src\] values;
+
+\| Input \| Output \| \|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--
+\| \| `/a/b.jpg` \| `http://example.org/a/b.jpg` \| \| `a/b.jpg` \|
+`http://example.org/foo/a/b.jpg` \| \| `a/b` \| `http://example.org/foo/a/b` \|
+\| `../a/b.jpg` \| `http://example.org/a/b.jpg` \| \| `a/b.jpg?foo=bar` \|
+`http://example.org/foo/a/b.jpg?foo=bar` \| \| `//example.org/a/b.jpg` \|
+`http://example.org/a/b.jpg` \| \| `http://elsewhere.org/a/b.jpg` \|
+`http://elsewhere.org/a/b.jpg` \| \| `https://example.org/a/b.jpg` \|
+`https://example.org/a/b.jpg` \|
+
+<b>Signature:</b>
+
+```typescript
+assetUrlNormalizer: (sourceDocument: string, asset: string) => string
+```