@mytechtoday/url-reference-mapper 1.3.0 → 2.0.0-alpha.1

package/dist/parsers/text-parser.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.truncateText = exports.getTextStats = exports.isPlainText = exports.extractUrls = exports.normalizeLineEndings = exports.parseText = void 0;
+const URL_REGEX = /https?:\/\/(www\.)?[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_+.~#?&//=]*)/gi;
+function parseText(content) {
+    try {
+        const normalizedText = normalizeLineEndings(content);
+        const urls = extractUrls(normalizedText);
+        const lines = normalizedText.split('\n');
+        const lineCount = lines.length;
+        const charCount = normalizedText.length;
+        return {
+            text: normalizedText,
+            urls,
+            lineCount,
+            charCount,
+        };
+    }
+    catch (error) {
+        console.warn('Text parsing error:', error);
+        return {
+            text: content,
+            urls: [],
+            lineCount: 1,
+            charCount: content.length,
+        };
+    }
+}
+exports.parseText = parseText;
+function normalizeLineEndings(text) {
+    return text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+exports.normalizeLineEndings = normalizeLineEndings;
+function extractUrls(text) {
+    const urls = [];
+    const matches = text.matchAll(URL_REGEX);
+    for (const match of matches) {
+        urls.push(match[0]);
+    }
+    return [...new Set(urls)];
+}
+exports.extractUrls = extractUrls;
+function isPlainText(content) {
+    if (content.includes('\0')) {
+        return false;
+    }
+    const printableChars = content.match(/[\x20-\x7E\n\r\t]/g)?.length || 0;
+    const totalChars = content.length;
+    if (totalChars === 0) {
+        return true;
+    }
+    const printableRatio = printableChars / totalChars;
+    return printableRatio > 0.8;
+}
+exports.isPlainText = isPlainText;
+function getTextStats(text) {
+    const normalizedText = normalizeLineEndings(text);
+    const lines = normalizedText.split('\n');
+    const words = normalizedText.split(/\s+/).filter(w => w.length > 0);
+    const urls = extractUrls(normalizedText);
+    return {
+        lines: lines.length,
+        words: words.length,
+        chars: normalizedText.length,
+        urls: urls.length,
+    };
+}
+exports.getTextStats = getTextStats;
+function truncateText(text, maxLength, suffix = '...') {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return text.substring(0, maxLength - suffix.length) + suffix;
+}
+exports.truncateText = truncateText;
+//# sourceMappingURL=text-parser.js.map

package/dist/parsers/text-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-parser.js","sourceRoot":"","sources":["../../src/parsers/text-parser.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -4,6 +4,20 @@ export interface UrlMapping {
     localPath: string;
     lastUpdated?: string;
     metadata?: Record<string, any>;
+    wordCount?: number;
+    readingTime?: number;
+    tags?: string;
+    summary?: string;
+    tldr?: string;
+    categories?: string;
+    author?: string;
+    featuredImages?: string[];
+    authorImage?: string;
+    authorUrl?: string;
+    quotes?: string[];
+    internalLinks?: string[];
+    externalLinks?: string[];
+    relatedPosts?: string[];
 }
 export interface UrlReferenceMapperConfig {
     configPath?: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IAEzB,KAAK,EAAE,MAAM,CAAC;IAEd,GAAG,EAAE,MAAM,CAAC;IAEZ,SAAS,EAAE,MAAM,CAAC;IAElB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAKD,MAAM,WAAW,wBAAwB;IAEvC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IAExB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAKD,MAAM,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAKpD,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,gBAAgB,CAAC;AAKrB,MAAM,MAAM,qBAAqB,GAC7B,oBAAoB,GACpB,eAAe,GACf,kBAAkB,GAClB,cAAc,CAAC;AAKnB,MAAM,WAAW,eAAe;IAE9B,IAAI,EAAE,mBAAmB,CAAC;IAE1B,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAKD,MAAM,WAAW,iBAAiB;IAEhC,IAAI,EAAE,qBAAqB,CAAC;IAE5B,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAKD,MAAM,WAAW,gBAAgB;IAE/B,KAAK,EAAE,OAAO,CAAC;IAEf,MAAM,EAAE,eAAe,EAAE,CAAC;IAE1B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAKD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IAEzB,KAAK,EAAE,MAAM,CAAC;IAEd,GAAG,EAAE,MAAM,CAAC;IAEZ,SAAS,EAAE,MAAM,CAAC;IAElB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAI/B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAKD,MAAM,WAAW,wBAAwB;IAEvC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IAExB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAKD,MAAM,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAKpD,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,gBAAgB,CAAC;AAKrB,MAAM,MAAM,qBAAqB,GAC7B,oBAAoB,GACpB,eAAe,GACf,kBAAkB,GAClB,cAAc,CAAC;AAKnB,MAAM,WAAW,eAAe;IAE9B,IAAI,EAAE,mBAAmB,CAAC;IAE1B,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAKD,MAAM,WAAW,iBAAiB;IAEhC,IAAI,EAAE,qBAAqB,CAAC;IAE5B,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAKD,MAAM,WAAW,gBAAgB;IAE/B,KAAK,EAAE,OAAO,CAAC;IAEf,MAAM,EAAE,eAAe,EAAE,CAAC;IAE1B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAKD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC"}

package/package.json

@@ -1,75 +1,74 @@
-{
-  "name": "@mytechtoday/url-reference-mapper",
-  "version": "1.3.0",
-  "description": "Bidirectional mapping between local filesystem paths and published internet URLs for Augment AI workflows",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "url-ref-mapper": "dist/cli.js"
-  },
-  "files": [
-    "dist/",
-    "schema.json",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "lint": "eslint src/**/*.ts",
-    "lint:fix": "eslint src/**/*.ts --fix",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "prepare": "npm run build",
-    "prepublishOnly": "npm run lint && npm run test && npm run build",
-    "validate": "node dist/cli.js validate"
-  },
-  "keywords": [
-    "url-mapping",
-    "path-mapping",
-    "augment-ai",
-    "openspec",
-    "beads",
-    "url-reference",
-    "filesystem",
-    "wordpress",
-    "static-site",
-    "developer-tools"
-  ],
-  "author": "MyTech.Today",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/mytech-today-now/url-reference.git"
-  },
-  "bugs": {
-    "url": "https://github.com/mytech-today-now/url-reference/issues"
-  },
-  "homepage": "https://github.com/mytech-today-now/url-reference#readme",
-  "engines": {
-    "node": ">=16.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "commander": "^11.0.0",
-    "js-yaml": "^4.1.1"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.0",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^20.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
-    "eslint": "^8.50.0",
-    "jest": "^29.7.0",
-    "prettier": "^3.0.0",
-    "ts-jest": "^29.1.0",
-    "typescript": "^5.3.3"
-  }
-}
-
+{
+  "name": "@mytechtoday/url-reference-mapper",
+  "version": "2.0.0-alpha.1",
+  "description": "Bidirectional mapping between local filesystem paths and published internet URLs for Augment AI workflows. v2.0.0 planning: Enhanced CLI with comprehensive help system, advanced features, and utility commands (in development).",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "url-ref-mapper": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "schema.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run lint && npm run test && npm run build",
+    "validate": "node dist/cli.js validate"
+  },
+  "keywords": [
+    "url-mapping",
+    "path-mapping",
+    "augment-ai",
+    "openspec",
+    "beads",
+    "url-reference",
+    "filesystem",
+    "wordpress",
+    "static-site",
+    "developer-tools"
+  ],
+  "author": "MyTech.Today",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mytech-today-now/url-reference.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mytech-today-now/url-reference/issues"
+  },
+  "homepage": "https://github.com/mytech-today-now/url-reference#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^11.0.0",
+    "js-yaml": "^4.1.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.50.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.0.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.3"
+  }
+}

package/schema.json

@@ -1,172 +1,172 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://github.com/mytech-today-now/url-reference/schema.json",
-  "title": "URL Reference Mapper Schema",
-  "description": "JSON Schema for @mytechtoday/url-reference-mapper package types",
-  "definitions": {
-    "UrlMapping": {
-      "type": "object",
-      "description": "Represents a bidirectional mapping between a local filesystem path and a published internet URL",
-      "required": ["title", "url", "localPath"],
-      "properties": {
-        "title": {
-          "type": "string",
-          "description": "Human-readable title for the mapping",
-          "minLength": 1,
-          "examples": [
-            "Copper ETFs and Investment Vehicles: 2026",
-            "Mid-Tier & Junior Copper Miners: 2026 Analysis"
-          ]
-        },
-        "url": {
-          "type": "string",
-          "format": "uri",
-          "description": "Published internet URL (must be a valid HTTP/HTTPS URL)",
-          "pattern": "^https?://",
-          "examples": [
-            "https://mytech.today/copper-etfs-and-investment-vehicles-2026/",
-            "https://example.com/blog/post-title/"
-          ]
-        },
-        "localPath": {
-          "type": "string",
-          "description": "Local filesystem path (absolute or relative). Absolute paths are recommended.",
-          "minLength": 1,
-          "examples": [
-            "G:\\blogs\\copper-mining-part-4-etf-investment-vehicles.html",
-            "/home/user/projects/blogs/post.html",
-            "C:\\projects\\blogs\\post.html"
-          ]
-        },
-        "lastUpdated": {
-          "type": "string",
-          "format": "date-time",
-          "description": "ISO 8601 timestamp of when the mapping was last updated",
-          "examples": [
-            "2026-01-27T17:04:00-06:00",
-            "2026-01-30T12:00:00Z"
-          ]
-        },
-        "metadata": {
-          "type": "object",
-          "description": "Optional additional metadata for the mapping",
-          "additionalProperties": true,
-          "examples": [
-            {
-              "category": "technology",
-              "tags": ["copper", "mining", "investment"],
-              "author": "John Doe"
-            }
-          ]
-        }
-      },
-      "additionalProperties": false
-    },
-    "ValidationErrorType": {
-      "type": "string",
-      "enum": [
-        "duplicate_url",
-        "duplicate_path",
-        "invalid_url",
-        "missing_file",
-        "invalid_format"
-      ],
-      "description": "Types of validation errors that can occur"
-    },
-    "ValidationWarningType": {
-      "type": "string",
-      "enum": [
-        "outdated_timestamp",
-        "relative_path",
-        "missing_metadata"
-      ],
-      "description": "Types of validation warnings that can occur"
-    },
-    "ValidationError": {
-      "type": "object",
-      "required": ["type", "message"],
-      "properties": {
-        "type": {
-          "$ref": "#/definitions/ValidationErrorType"
-        },
-        "message": {
-          "type": "string",
-          "description": "Human-readable error message"
-        },
-        "mapping": {
-          "$ref": "#/definitions/UrlMapping",
-          "description": "The mapping that caused the error"
-        }
-      }
-    },
-    "ValidationWarning": {
-      "type": "object",
-      "required": ["type", "message"],
-      "properties": {
-        "type": {
-          "$ref": "#/definitions/ValidationWarningType"
-        },
-        "message": {
-          "type": "string",
-          "description": "Human-readable warning message"
-        },
-        "mapping": {
-          "$ref": "#/definitions/UrlMapping",
-          "description": "The mapping that caused the warning"
-        }
-      }
-    },
-    "ValidationResult": {
-      "type": "object",
-      "required": ["valid", "errors", "warnings"],
-      "properties": {
-        "valid": {
-          "type": "boolean",
-          "description": "Whether all mappings are valid"
-        },
-        "errors": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/ValidationError"
-          },
-          "description": "Array of validation errors"
-        },
-        "warnings": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/ValidationWarning"
-          },
-          "description": "Array of validation warnings"
-        }
-      }
-    },
-    "MapperConfig": {
-      "type": "object",
-      "description": "Configuration options for UrlReferenceMapper",
-      "properties": {
-        "configPath": {
-          "type": "string",
-          "description": "Path to configuration file (JSON or YAML)"
-        },
-        "mappings": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/UrlMapping"
-          },
-          "description": "Inline mappings (alternative to configPath)"
-        },
-        "autoSave": {
-          "type": "boolean",
-          "default": false,
-          "description": "Automatically save changes to file"
-        },
-        "validateOnLoad": {
-          "type": "boolean",
-          "default": true,
-          "description": "Validate mappings when loading"
-        }
-      }
-    }
-  }
-}
-
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/mytech-today-now/url-reference/schema.json",
+  "title": "URL Reference Mapper Schema",
+  "description": "JSON Schema for @mytechtoday/url-reference-mapper package types",
+  "definitions": {
+    "UrlMapping": {
+      "type": "object",
+      "description": "Represents a bidirectional mapping between a local filesystem path and a published internet URL",
+      "required": ["title", "url", "localPath"],
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "Human-readable title for the mapping",
+          "minLength": 1,
+          "examples": [
+            "Copper ETFs and Investment Vehicles: 2026",
+            "Mid-Tier & Junior Copper Miners: 2026 Analysis"
+          ]
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Published internet URL (must be a valid HTTP/HTTPS URL)",
+          "pattern": "^https?://",
+          "examples": [
+            "https://mytech.today/copper-etfs-and-investment-vehicles-2026/",
+            "https://example.com/blog/post-title/"
+          ]
+        },
+        "localPath": {
+          "type": "string",
+          "description": "Local filesystem path (absolute or relative). Absolute paths are recommended.",
+          "minLength": 1,
+          "examples": [
+            "G:\\blogs\\copper-mining-part-4-etf-investment-vehicles.html",
+            "/home/user/projects/blogs/post.html",
+            "C:\\projects\\blogs\\post.html"
+          ]
+        },
+        "lastUpdated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of when the mapping was last updated",
+          "examples": [
+            "2026-01-27T17:04:00-06:00",
+            "2026-01-30T12:00:00Z"
+          ]
+        },
+        "metadata": {
+          "type": "object",
+          "description": "Optional additional metadata for the mapping",
+          "additionalProperties": true,
+          "examples": [
+            {
+              "category": "technology",
+              "tags": ["copper", "mining", "investment"],
+              "author": "John Doe"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "ValidationErrorType": {
+      "type": "string",
+      "enum": [
+        "duplicate_url",
+        "duplicate_path",
+        "invalid_url",
+        "missing_file",
+        "invalid_format"
+      ],
+      "description": "Types of validation errors that can occur"
+    },
+    "ValidationWarningType": {
+      "type": "string",
+      "enum": [
+        "outdated_timestamp",
+        "relative_path",
+        "missing_metadata"
+      ],
+      "description": "Types of validation warnings that can occur"
+    },
+    "ValidationError": {
+      "type": "object",
+      "required": ["type", "message"],
+      "properties": {
+        "type": {
+          "$ref": "#/definitions/ValidationErrorType"
+        },
+        "message": {
+          "type": "string",
+          "description": "Human-readable error message"
+        },
+        "mapping": {
+          "$ref": "#/definitions/UrlMapping",
+          "description": "The mapping that caused the error"
+        }
+      }
+    },
+    "ValidationWarning": {
+      "type": "object",
+      "required": ["type", "message"],
+      "properties": {
+        "type": {
+          "$ref": "#/definitions/ValidationWarningType"
+        },
+        "message": {
+          "type": "string",
+          "description": "Human-readable warning message"
+        },
+        "mapping": {
+          "$ref": "#/definitions/UrlMapping",
+          "description": "The mapping that caused the warning"
+        }
+      }
+    },
+    "ValidationResult": {
+      "type": "object",
+      "required": ["valid", "errors", "warnings"],
+      "properties": {
+        "valid": {
+          "type": "boolean",
+          "description": "Whether all mappings are valid"
+        },
+        "errors": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ValidationError"
+          },
+          "description": "Array of validation errors"
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ValidationWarning"
+          },
+          "description": "Array of validation warnings"
+        }
+      }
+    },
+    "MapperConfig": {
+      "type": "object",
+      "description": "Configuration options for UrlReferenceMapper",
+      "properties": {
+        "configPath": {
+          "type": "string",
+          "description": "Path to configuration file (JSON or YAML)"
+        },
+        "mappings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/UrlMapping"
+          },
+          "description": "Inline mappings (alternative to configPath)"
+        },
+        "autoSave": {
+          "type": "boolean",
+          "default": false,
+          "description": "Automatically save changes to file"
+        },
+        "validateOnLoad": {
+          "type": "boolean",
+          "default": true,
+          "description": "Validate mappings when loading"
+        }
+      }
+    }
+  }
+}
+