@vibe-agent-toolkit/resources 0.1.37 → 0.1.38

package/src/rewriter-helpers.ts

@@ -0,0 +1,166 @@
+/**
+ * Public rewriter helpers built on FrontmatterEditor and shared callback
+ * shape `(href: string) => string`.
+ *
+ * Three layers:
+ *   1. rewriteFrontmatterUriReferencesFromSchema — schema-driven; used by
+ *      VAT packager and by schema-aware adopter scripts.
+ *   2. rewriteFrontmatterFieldsAtPaths — path-driven; used by ad-hoc
+ *      adopter scripts (no JSON Schema available; field paths known by
+ *      convention).
+ *   3. rewriteBodyLinks — standalone body-side counterpart. Parallel to
+ *      `transformContent` but with a callback model instead of templates.
+ *
+ * See docs/superpowers/specs/2026-05-17-frontmatter-editor-and-yaml-consolidation-design.md
+ * §6 for the design contract.
+ */
+
+import { isNode } from 'yaml';
+
+import type { FrontmatterEditor } from './frontmatter-editor.js';
+import { jsonPointerToPath } from './json-pointer-path.js';
+import { walkFrontmatterUriReferences } from './schema-uri-walker.js';
+
+/**
+ * Normalize a value returned by `FrontmatterEditor.get(path)` into plain JS.
+ *
+ * The underlying yaml library's `getIn(path, false)` unwraps scalar leaves to
+ * JS primitives but leaves YAMLMap / YAMLSeq collections as Node instances.
+ * The rewriter helpers reason in terms of JS values (arrays, strings), so we
+ * unwrap collection Nodes here once at the boundary.
+ */
+function toPlainJs(value: unknown): unknown {
+  if (isNode(value)) return value.toJSON();
+  return value;
+}
+
+/** Type for the rewrite policy callback — same shape for body and frontmatter. */
+export type RewriteHref = (href: string) => string;
+
+/**
+ * Apply `rewriteHref` to every frontmatter scalar whose schema position has
+ * a URI-family `format`. Preserves comments via FrontmatterEditor.
+ */
+export function rewriteFrontmatterUriReferencesFromSchema(
+  editor: FrontmatterEditor,
+  schema: object,
+  rewriteHref: RewriteHref,
+): void {
+  const frontmatter = editor.get([]);
+  if (frontmatter === undefined || frontmatter === null) return;
+  if (typeof frontmatter !== 'object') return;
+
+  const captures = walkFrontmatterUriReferences(frontmatter, schema);
+  for (const capture of captures) {
+    const path = jsonPointerToPath(capture.pointer);
+    if (path.length === 0) continue;
+    const newValue = rewriteHref(capture.value);
+    if (newValue === capture.value) continue;
+    const lastSegment = path.at(-1);
+    if (typeof lastSegment === 'number') {
+      const parentPath = path.slice(0, -1);
+      editor.setArrayItem(parentPath, lastSegment, newValue);
+    } else {
+      editor.set(path, newValue);
+    }
+  }
+}
+
+interface ParsedPath {
+  segments: readonly (string | number)[];
+  isArray: boolean;
+}
+
+function parsePathPattern(pattern: string): ParsedPath {
+  const isArray = pattern.endsWith('[]');
+  const cleaned = isArray ? pattern.slice(0, -2) : pattern;
+  const segments = cleaned.split('.');
+  return { segments, isArray };
+}
+
+function rewriteArrayPath(
+  editor: FrontmatterEditor,
+  segments: readonly (string | number)[],
+  value: unknown,
+  rewriteHref: RewriteHref,
+): void {
+  if (!Array.isArray(value)) return;
+  for (const [i, item] of value.entries()) {
+    if (typeof item !== 'string') continue;
+    const newValue = rewriteHref(item);
+    if (newValue !== item) editor.setArrayItem(segments, i, newValue);
+  }
+}
+
+function rewriteScalarPath(
+  editor: FrontmatterEditor,
+  segments: readonly (string | number)[],
+  value: unknown,
+  rewriteHref: RewriteHref,
+): void {
+  if (typeof value !== 'string') return;
+  const newValue = rewriteHref(value);
+  if (newValue !== value) editor.set(segments, newValue);
+}
+
+/**
+ * Apply `rewriteHref` to specific frontmatter fields named by explicit
+ * dotted paths. Used by adopter scripts that know which fields hold
+ * references without a JSON Schema.
+ *
+ * Path syntax:
+ *   - 'name'            — top-level scalar
+ *   - 'name[]'          — array of strings (rewrite each string item)
+ *   - 'meta.parent'     — dotted nested scalar
+ *   - 'meta.refs[]'     — dotted nested array of strings
+ *
+ * Missing paths are silent no-ops. Non-string values are skipped.
+ */
+export function rewriteFrontmatterFieldsAtPaths(
+  editor: FrontmatterEditor,
+  paths: readonly string[],
+  rewriteHref: RewriteHref,
+): void {
+  for (const pattern of paths) {
+    const { segments, isArray } = parsePathPattern(pattern);
+    const value = toPlainJs(editor.get(segments));
+    if (value === undefined || value === null) continue;
+    if (isArray) {
+      rewriteArrayPath(editor, segments, value, rewriteHref);
+    } else {
+      rewriteScalarPath(editor, segments, value, rewriteHref);
+    }
+  }
+}
+
+/**
+ * Inline + reference-style link patterns. These match `transformContent`'s
+ * regex contract — see content-transform.ts for the rationale on negated
+ * character classes.
+ */
+// eslint-disable-next-line sonarjs/slow-regex -- negated character classes [^\]] and [^)] are non-backtracking
+const INLINE_LINK_REGEX = /\[([^\]]*)\]\(([^)]*)\)/g;
+// eslint-disable-next-line sonarjs/slow-regex -- Controlled markdown reference link definitions on line boundaries
+const DEFINITION_LINK_REGEX = /^\[([^\]]*?)\]:\s*(.+)$/gm;
+
+/**
+ * Apply `rewriteHref` to every inline-link and reference-definition href in
+ * a markdown body. Parallel to `transformContent` but with a callback model
+ * — appropriate for adopter scripts and for any caller that wants a
+ * per-href rewrite without rule/template ceremony.
+ *
+ * `rewriteHref` receives the raw href (including any fragment) and returns
+ * the new href. Returning the same string is a no-op for that link.
+ */
+export function rewriteBodyLinks(body: string, rewriteHref: RewriteHref): string {
+  let out = body.replaceAll(INLINE_LINK_REGEX, (full, text: string, href: string) => {
+    const next = rewriteHref(href);
+    return next === href ? full : `[${text}](${next})`;
+  });
+  out = out.replaceAll(DEFINITION_LINK_REGEX, (full, ref: string, href: string) => {
+    const trimmed = href.trim();
+    const next = rewriteHref(trimmed);
+    return next === trimmed ? full : `[${ref}]: ${next}`;
+  });
+  return out;
+}

package/src/types/resource-parser.ts

@@ -7,7 +7,7 @@
 
 import { promises as fs } from 'node:fs';
 
-import yaml from 'js-yaml';
+import * as yaml from 'yaml';
 
 import { calculateChecksum } from '../checksum.js';
 import { parseMarkdown } from '../link-parser.js';
@@ -213,8 +213,7 @@ export async function parseYamlResource(
   // Read and parse YAML
   // eslint-disable-next-line security/detect-non-literal-fs-filename
   const content = await fs.readFile(absolutePath, 'utf-8');
-  // CORE_SCHEMA: YAML 1.2 spec — see link-parser.ts for rationale.
-  const data = yaml.load(content, { schema: yaml.CORE_SCHEMA });
+  const data = yaml.parse(content);
 
   // Calculate checksum
   const checksum = await calculateChecksum(absolutePath);

package/src/types.ts

@@ -89,7 +89,6 @@ export type {
 
 // Config parsing
 export {
-  findConfigFile,
   parseConfigFile,
   loadConfig,
 } from './config-parser.js';

package/src/utils.ts

@@ -73,35 +73,58 @@ export function splitHrefAnchor(href: string): [string, string | undefined] {
 }
 
 /**
- * Resolve a markdown link href to an absolute filesystem path.
+ * Discriminated union returned by {@link resolveLocalHref}.
+ *
+ * - `anchor_only` — the href was `#fragment` only (no file component).
+ * - `resolved` — the href resolved to an absolute filesystem path.
+ * - `absolute_no_root` — the href is an RFC 3986 §4.2 absolute-path
+ *   reference (starts with `/`) but no `projectRoot` was supplied.
+ * - `absolute_escapes_root` — the absolute-path reference resolved to a
+ *   location outside `projectRoot` (e.g., via `..` traversal or a symlink
+ *   pointing outside the project).
+ */
+export type ResolveLocalHrefResult =
+  | { kind: 'anchor_only' }
+  | { kind: 'resolved'; resolvedPath: string; anchor: string | undefined }
+  | { kind: 'absolute_no_root'; href: string; anchor: string | undefined }
+  | { kind: 'absolute_escapes_root'; href: string; anchor: string | undefined };
+
+/**
+ * Resolve a markdown link href to a filesystem path or a typed failure.
  *
  * Performs the standard href → path conversion used by both audit and validate:
  * 1. Strips anchor fragment (`#section`)
  * 2. Decodes URL-encoded characters (`%20` → space, `%26` → `&`)
- * 3. Resolves the path relative to the source file's directory
- *
- * Returns `null` for anchor-only links (e.g., `#heading`).
+ * 3. Resolves the path:
+ *    - Leading `/` (RFC 3986 §4.2 absolute-path reference) → resolve against
+ *      `projectRoot`. Requires a `projectRoot`; must not escape it.
+ *    - Otherwise → resolve relative to the source file's directory.
  *
  * @param href - Raw href from a markdown link
  * @param sourceFilePath - Absolute path of the file containing the link
- * @returns Resolved path info, or null for anchor-only links
+ * @param projectRoot - Optional project root for absolute-path references.
+ * @returns A {@link ResolveLocalHrefResult} discriminating success vs failure modes.
  *
  * @example
  * ```typescript
  * resolveLocalHref('My%20Folder/doc.md#intro', '/project/README.md')
- * // { resolvedPath: '/project/My Folder/doc.md', anchor: 'intro' }
+ * // { kind: 'resolved', resolvedPath: '/project/My Folder/doc.md', anchor: 'intro' }
  *
  * resolveLocalHref('#heading', '/project/README.md')
- * // null
+ * // { kind: 'anchor_only' }
+ *
+ * resolveLocalHref('/docs/foo.md', '/project/docs/sub/page.md', '/project')
+ * // { kind: 'resolved', resolvedPath: '/project/docs/foo.md', anchor: undefined }
  * ```
  */
 export function resolveLocalHref(
   href: string,
   sourceFilePath: string,
-): { resolvedPath: string; anchor: string | undefined } | null {
+  projectRoot?: string,
+): ResolveLocalHrefResult {
   const [fileHref, anchor] = splitHrefAnchor(href);
   if (fileHref === '') {
-    return null;
+    return { kind: 'anchor_only' };
   }
 
   let decodedHref: string;
@@ -111,10 +134,22 @@ export function resolveLocalHref(
     decodedHref = fileHref;
   }
 
+  // RFC 3986 §4.2 absolute-path reference — resolve against projectRoot.
+  if (decodedHref.startsWith('/')) {
+    if (!projectRoot) {
+      return { kind: 'absolute_no_root', href: fileHref, anchor };
+    }
+    const candidate = safePath.resolve(projectRoot, decodedHref.slice(1));
+    if (!isWithinProject(candidate, projectRoot)) {
+      return { kind: 'absolute_escapes_root', href: fileHref, anchor };
+    }
+    return { kind: 'resolved', resolvedPath: candidate, anchor };
+  }
+
+  // Relative reference — resolve against the source file's directory.
   const sourceDir = path.dirname(sourceFilePath);
   const resolvedPath = safePath.resolve(sourceDir, decodedHref);
-
-  return { resolvedPath, anchor };
+  return { kind: 'resolved', resolvedPath, anchor };
 }
 
 /**
@@ -135,7 +170,9 @@ export function resolveLocalHref(
  * ```
  */
 export function isWithinProject(filePath: string, projectRoot: string): boolean {
-  // Resolve symlinks to get real paths
+  // Canonicalize both sides symmetrically. Asymmetric handling (realpath one
+  // side, resolve the other) false-flags legitimate matches when projectRoot
+  // traverses a symlink — e.g. macOS /tmp → /private/tmp, bind mounts.
   let resolvedFilePath: string;
   try {
     // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is validated path parameter
@@ -145,7 +182,13 @@ export function isWithinProject(filePath: string, projectRoot: string): boolean
     resolvedFilePath = safePath.resolve(filePath);
   }
 
-  const resolvedProjectRoot = safePath.resolve(projectRoot);
+  let resolvedProjectRoot: string;
+  try {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- projectRoot is validated path parameter
+    resolvedProjectRoot = fs.realpathSync(projectRoot);
+  } catch {
+    resolvedProjectRoot = safePath.resolve(projectRoot);
+  }
 
   // Normalize to forward slashes for cross-platform comparison
   const normalizedFile = toForwardSlash(resolvedFilePath);
@@ -199,7 +242,7 @@ export function formatJsonPointerAsDotted(pointer: string): string {
   return out;
 }
 
-function isCanonicalArrayIndex(s: string): boolean {
+export function isCanonicalArrayIndex(s: string): boolean {
   // Canonical integer per RFC 6901 §4 + JSON canonical form: no leading zeros
   // except for "0" itself.
   if (s === '') return false;