@thi.ng/tangle 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-09-21T21:37:59Z
+- **Last updated**: 2022-09-22T10:09:17Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,13 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+### [0.1.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/tangle@0.1.1) (2022-09-22)
+
+#### 🩹 Bug fixes
+
+- in-memory rel path handling ([d184eb2](https://github.com/thi-ng/umbrella/commit/d184eb2))
+  - update test fixtures
+
 ## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/tangle@0.1.0) (2022-09-21)
 
 #### 🚀 Features

package/README.md

@@ -271,7 +271,11 @@ The published version of the input markdown file: `out/main.md`
 
 ### VSCode
 
-Using the [Run On Save extension](https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave), tangling can be automatically performed on each save of an Literate Programming source file. E.g. this configuration (add to your VSCode workspace `settings.json`) runs the tangle command on each save of a `*.lit.md` file.
+Using the [Run On Save
+extension](https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave),
+tangling can be automatically performed on each save of an Literate Programming
+source file. E.g. this configuration (add to your VSCode workspace
+`settings.json`) runs the tangle command on each save of a `*.lit.md` file.
 
 ```json
 "emeraldwalk.runonsave": {
@@ -284,7 +288,8 @@ Using the [Run On Save extension](https://marketplace.visualstudio.com/items?ite
 }
 ```
 
-Note: This also assumes you have this package (@thi.ng/tangle) added to your dependencies...
+Note: This also assumes you have this package (@thi.ng/tangle) added to your
+dependencies...
 
 ### Other editors
 
@@ -319,7 +324,7 @@ node --experimental-repl-await
 > const tangle = await import("@thi.ng/tangle");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 1.96 KB
+Package sizes (gzipped, pre-treeshake): ESM: 1.97 KB
 
 ## Dependencies
 
@@ -338,7 +343,13 @@ Package sizes (gzipped, pre-treeshake): ESM: 1.96 KB
 
 [Generated API docs](https://docs.thi.ng/umbrella/tangle/)
 
-TODO
+In addition to the CLI wrapper, the package provides the
+[`tangleFile()`](https://docs.thi.ng/umbrella/tangle/modules.html#tangleFile)
+and
+[`tangleString()`](https://docs.thi.ng/umbrella/tangle/modules.html#tangleString)
+functions. See
+[/test/index.ts](https://github.com/thi-ng/umbrella/blob/develop/packages/tangle/test/index.ts)
+for usage examples.
 
 ## Authors
 

package/api.d.ts

@@ -21,11 +21,33 @@ export interface TangleRef {
 }
 export declare type Blocks = Record<string, Block>;
 export interface TangleCtx {
+    /**
+     * Code block marker definitions for current source file format. If not
+     * pre-defined, then {@link tangleFile} will auto-detect the format based on
+     * given file extension. See {@link BLOCK_FORMATS} for supported source
+     * formats.
+     */
     format: CodeBlockFormat;
+    /**
+     * Stores all referenced source files and their extracted code blocks.
+     */
     files: Record<string, TangleRef>;
+    /**
+     * Stores all generated outputs (absolute file paths are used as keys)
+     */
     outputs: Record<string, string>;
+    /**
+     * Logger for debug outputs
+     */
     logger: ILogger;
+    /**
+     * "Filesystem" implementation. When using {@link tangleString}, in-memory
+     * stubs will be used to obtain file contents from a given object.
+     */
     fs: FileSystem;
+    /**
+     * Tangle & codegen options
+     */
     opts: Partial<TangleOpts>;
 }
 export interface FileSystem {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/tangle",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Literate programming code block tangling / codegen utility, inspired by org-mode & noweb",
   "type": "module",
   "module": "./index.js",
@@ -91,5 +91,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "973139c5aa3b50081020f4cc726a7cc330f77fc7\n"
+  "gitHead": "84d9d694065457d30eafc3556f93a307b78b20fb\n"
 }

package/tangle.d.ts

@@ -1,5 +1,16 @@
 import type { IObjectOf } from "@thi.ng/api";
 import { TangleCtx } from "./api.js";
+/**
+ * Takes a file `path` and partial {@link TangleCtx}. Reads "file"
+ * (implementation specific, could be from memory or other source) and then
+ * performs all tangling steps on the document body, i.e. expanding &
+ * transcluding code blocks, generating outputs for various target files etc.
+ * Returns updated TangleCtx with all generated outputs stored under the
+ * {@link TangleCtx.outputs} key.
+ *
+ * @param path
+ * @param ctx
+ */
 export declare const tangleFile: (path: string, ctx?: Partial<TangleCtx>) => TangleCtx;
 /**
  * In-memory version of {@link tangleFile}. Take a file name and an object of
@@ -8,8 +19,8 @@ export declare const tangleFile: (path: string, ctx?: Partial<TangleCtx>) => Tan
  * virtual "file system" (of sorts).
  *
  * @remarks
- * All file references are considered absolute paths, i.e. `foo.md` is okay, but
- * `../foo/bar.md` is NOT supported.
+ * Relative file reference paths are only supported if they refer to children or
+ * siblings, i.e. `foo/bar.md` is okay, but `../foo/bar.md` is NOT supported.
  *
  * @param fileID
  * @param files

package/tangle.js

@@ -114,6 +114,17 @@ const loadAndResolveBlocks = (path, ctx) => {
     }
     return ctx.files[path];
 };
+/**
+ * Takes a file `path` and partial {@link TangleCtx}. Reads "file"
+ * (implementation specific, could be from memory or other source) and then
+ * performs all tangling steps on the document body, i.e. expanding &
+ * transcluding code blocks, generating outputs for various target files etc.
+ * Returns updated TangleCtx with all generated outputs stored under the
+ * {@link TangleCtx.outputs} key.
+ *
+ * @param path
+ * @param ctx
+ */
 export const tangleFile = (path, ctx = {}) => {
     const fmt = ctx.format || BLOCK_FORMATS[extname(path)];
     !fmt && illegalArgs(`unsupported file type: ${extname(path)}`);
@@ -182,8 +193,8 @@ export const tangleFile = (path, ctx = {}) => {
  * virtual "file system" (of sorts).
  *
  * @remarks
- * All file references are considered absolute paths, i.e. `foo.md` is okay, but
- * `../foo/bar.md` is NOT supported.
+ * Relative file reference paths are only supported if they refer to children or
+ * siblings, i.e. `foo/bar.md` is okay, but `../foo/bar.md` is NOT supported.
  *
  * @param fileID
  * @param files
@@ -191,7 +202,7 @@ export const tangleFile = (path, ctx = {}) => {
  */
 export const tangleString = (fileID, files, ctx = {}) => tangleFile(fileID, {
     fs: {
-        isAbsolute: () => true,
+        isAbsolute: (path) => path[0] === "/" || path[0] === "\\",
         resolve: (...path) => path[path.length - 1],
         read: (path, logger) => {
             logger.debug("reading file ref", path);