patram 0.1.1 → 0.3.0

package/lib/tagged-fenced-blocks.js

@@ -0,0 +1,100 @@
+/**
+ * @import {
+ *   TaggedFencedBlock,
+ *   TaggedFencedBlockCriteria,
+ *   TaggedFencedBlockFile,
+ *   TaggedFencedBlocksInput,
+ * } from './tagged-fenced-blocks.types.ts';
+ */
+
+import { readFile } from 'node:fs/promises';
+
+import { createTaggedFencedBlockError } from './tagged-fenced-block-error.js';
+import { extractTaggedFencedBlocksFromSource } from './tagged-fenced-block-parser.js';
+
+/**
+ * Tagged fenced block public API.
+ *
+ * Loads or extracts one markdown file worth of tagged fenced blocks and
+ * provides exact-match selection helpers.
+ *
+ * Kind: parse
+ * Status: active
+ * Tracked in: ../docs/plans/v0/tagged-fenced-block-extraction.md
+ * Decided by: ../docs/decisions/tagged-fenced-block-extraction.md
+ * @patram
+ * @see {@link ../docs/decisions/tagged-fenced-block-extraction.md}
+ */
+
+/**
+ * @param {TaggedFencedBlocksInput} input
+ * @returns {TaggedFencedBlockFile}
+ */
+export function extractTaggedFencedBlocks(input) {
+  return extractTaggedFencedBlocksFromSource(input);
+}
+
+/**
+ * @param {string} file_path
+ * @returns {Promise<TaggedFencedBlockFile>}
+ */
+export async function loadTaggedFencedBlocks(file_path) {
+  const source_text = await readFile(file_path, 'utf8');
+
+  return extractTaggedFencedBlocks({
+    file_path,
+    source_text,
+  });
+}
+
+/**
+ * @param {TaggedFencedBlock[]} blocks
+ * @param {TaggedFencedBlockCriteria} criteria
+ * @returns {TaggedFencedBlock[]}
+ */
+export function selectTaggedBlocks(blocks, criteria) {
+  const criteria_entries = Object.entries(criteria);
+
+  return blocks.filter((block) =>
+    criteria_entries.every(
+      ([key, value]) =>
+        block.metadata[key] !== undefined && block.metadata[key] === value,
+    ),
+  );
+}
+
+/**
+ * @param {TaggedFencedBlock[]} blocks
+ * @param {TaggedFencedBlockCriteria} criteria
+ * @returns {TaggedFencedBlock}
+ */
+export function selectTaggedBlock(blocks, criteria) {
+  const matches = selectTaggedBlocks(blocks, criteria);
+
+  if (matches.length === 1) {
+    return matches[0];
+  }
+
+  if (matches.length === 0) {
+    throw createTaggedFencedBlockError(
+      'tagged_fenced_blocks.not_found',
+      `No tagged fenced block matches ${formatSelectionCriteria(criteria)}.`,
+    );
+  }
+
+  throw createTaggedFencedBlockError(
+    'tagged_fenced_blocks.not_unique',
+    `Multiple tagged fenced blocks match ${formatSelectionCriteria(criteria)}.`,
+  );
+}
+
+/**
+ * @param {TaggedFencedBlockCriteria} criteria
+ * @returns {string}
+ */
+function formatSelectionCriteria(criteria) {
+  return Object.entries(criteria)
+    .sort(([left_key], [right_key]) => left_key.localeCompare(right_key))
+    .map(([key, value]) => `${key}=${value}`)
+    .join(', ');
+}

package/lib/tagged-fenced-blocks.types.ts

@@ -0,0 +1,38 @@
+export interface TaggedFencedBlocksInput {
+  file_path: string;
+  source_text: string;
+}
+
+export interface TaggedFencedBlockCriteria {
+  [key: string]: string;
+}
+
+export interface TaggedFencedBlockOrigin {
+  path: string;
+  line_start: number;
+  line_end: number;
+  tag_lines: number[];
+}
+
+export interface TaggedFencedBlockContext {
+  heading_path: string[];
+}
+
+export interface TaggedFencedBlock {
+  id: string;
+  lang: string;
+  value: string;
+  metadata: Record<string, string>;
+  origin: TaggedFencedBlockOrigin;
+  context: TaggedFencedBlockContext;
+}
+
+export interface TaggedFencedBlockFile {
+  path: string;
+  title: string;
+  blocks: TaggedFencedBlock[];
+}
+
+export interface TaggedFencedBlockError extends Error {
+  code: string;
+}

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "patram",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "type": "module",
+  "main": "./lib/patram.js",
+  "exports": {
+    ".": "./lib/patram.js",
+    "./bin/patram.js": "./bin/patram.js"
+  },
   "files": [
     "bin/patram.js",
     "lib/**/*.js",
@@ -12,7 +17,7 @@
     "!lib/**/*.test-helpers.js"
   ],
   "bin": {
-    "patram": "./bin/patram.js"
+    "patram": "bin/patram.js"
   },
   "homepage": "https://github.com/mantoni/patram",
   "repository": {
@@ -29,7 +34,7 @@
     "check:format": "prettier --check .",
     "check:lint": "eslint .",
     "check:patram": "./bin/patram.js check",
-    "check:staged": "lint-staged --quiet",
+    "check:staged": "lint-staged",
     "check:types": "tsc",
     "postversion": "git push && git push --tags",
     "preversion": "npm run all",
@@ -60,8 +65,8 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.12.0",
-    "@vitest/coverage-v8": "^4.1.0",
-    "eslint": "^10.0.3",
+    "@vitest/coverage-v8": "^4.1.1",
+    "eslint": "^10.1.0",
     "eslint-plugin-jsdoc": "^62.8.0",
     "globals": "^17.4.0",
     "husky": "^9.1.7",
@@ -69,7 +74,7 @@
     "lint-staged": "^16.2.6",
     "prettier": "^3.5.3",
     "slice-ansi": "^8.0.0",
-    "typescript": "^5.8.2",
-    "vitest": "^4.1.0"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.1"
   }
 }