refactor: centralize ims package path resolution

Move IMS CP path normalization into a shared core module so package graph analysis and QTI 3 delivery context use the same checked and permissive resolution rules.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: chillenious

packages/ims-cp-core/src/index.ts

@@ -4,6 +4,7 @@
  */
 
 export * from './manifest-parser.js';
+export * from './package-path.js';
 export * from './package-graph.js';
 export * from './localized-resources.js';
 export * from './passage-reusability.js';

packages/ims-cp-core/src/package-graph.ts

@@ -1,4 +1,10 @@
 import { type ManifestResource, type ParsedManifest, parseManifest } from './manifest-parser.js';
+import {
+	dirnamePackagePath,
+	isExternalPackageHref,
+	joinPackagePath,
+	resolvePackagePath,
+} from './package-path.js';
 
 export type PackageDiagnosticSeverity = 'info' | 'warning' | 'error';
 
@@ -385,7 +391,7 @@ function discoverReferences(xml: string, owner: PackageResourceNode): {
 } {
 	const references: PackageReference[] = [];
 	const assets: PackageAssetRef[] = [];
-	const basePath = owner.resolvedHref ? dirname(owner.resolvedHref) : '';
+	const basePath = owner.resolvedHref ? dirnamePackagePath(owner.resolvedHref) : '';
 
 	for (const match of findAttributeReferences(xml)) {
 		const resolvedPath = resolvePackagePath(basePath, match.rawHref);
@@ -433,7 +439,7 @@ function findAttributeReferences(xml: string): Array<{
 		const attrs = match.groups?.attrs ?? '';
 		const attribute = element === 'object' ? 'data' : element === 'img' ? 'src' : 'href';
 		const rawHref = readAttribute(attrs, attribute) ?? readAttribute(attrs, 'src') ?? readAttribute(attrs, 'href');
-		if (!rawHref || isExternalHref(rawHref)) continue;
+		if (!rawHref || isExternalPackageHref(rawHref)) continue;
 		refs.push({
 			kind: kindFromElement(element),
 			element,
@@ -583,35 +589,6 @@ function readAttribute(attrs: string, name: string): string | undefined {
 	return match?.[1];
 }
 
-function isExternalHref(href: string): boolean {
-	return /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i.test(href);
-}
-
-function joinPackagePath(...parts: Array<string | undefined>): string {
-	return parts.filter(Boolean).join('/');
-}
-
-function resolvePackagePath(basePath: string | undefined, href: string): string {
-	const raw = href.replaceAll('\\', '/');
-	const combined = raw.startsWith('/') ? raw.slice(1) : joinPackagePath(basePath, raw);
-	const normalized: string[] = [];
-	for (const part of combined.split('/')) {
-		if (!part || part === '.') continue;
-		if (part === '..') {
-			normalized.pop();
-			continue;
-		}
-		normalized.push(part);
-	}
-	return normalized.join('/');
-}
-
-function dirname(path: string): string {
-	const normalized = path.replaceAll('\\', '/');
-	const index = normalized.lastIndexOf('/');
-	return index === -1 ? '' : normalized.slice(0, index);
-}
-
 async function packagePathExists(
 	path: string,
 	fileAccess: PackageFileAccess,

packages/ims-cp-core/src/package-path.ts

@@ -0,0 +1,67 @@
+export interface PackagePathResolutionOptions {
+	rejectRootEscape?: boolean;
+}
+
+export function joinPackagePath(...parts: Array<string | undefined>): string {
+	return parts.filter(Boolean).join('/');
+}
+
+export function dirnamePackagePath(path: string): string {
+	const normalized = path.replaceAll('\\', '/');
+	const index = normalized.lastIndexOf('/');
+	return index === -1 ? '' : normalized.slice(0, index);
+}
+
+export function resolvePackagePath(basePath: string | undefined, href: string): string {
+	return resolvePackagePathInternal(basePath, href).path;
+}
+
+export function resolvePackagePathFromFile(baseHref: string, href: string): string {
+	return resolvePackagePath(dirnamePackagePath(baseHref), href);
+}
+
+export function resolveCheckedPackagePath(basePath: string | undefined, href: string): string | null {
+	if (!isPackageRelativeHref(href)) return null;
+	const result = resolvePackagePathInternal(basePath, href, { rejectRootEscape: true });
+	return result.escapedRoot ? null : result.path;
+}
+
+export function resolveCheckedPackagePathFromFile(baseHref: string, href: string): string | null {
+	return resolveCheckedPackagePath(dirnamePackagePath(baseHref), href);
+}
+
+export function isPackageRelativeHref(href: string): boolean {
+	const value = href.trim();
+	return Boolean(value) && !value.startsWith('/') && !value.startsWith('//') && !/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(value);
+}
+
+export function isExternalPackageHref(href: string): boolean {
+	return /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i.test(href);
+}
+
+function resolvePackagePathInternal(
+	basePath: string | undefined,
+	href: string,
+	options: PackagePathResolutionOptions = {}
+): { path: string; escapedRoot: boolean } {
+	const raw = href.replaceAll('\\', '/');
+	const combined = raw.startsWith('/') ? raw.slice(1) : joinPackagePath(basePath, raw);
+	const normalized: string[] = [];
+	let escapedRoot = false;
+
+	for (const part of combined.split('/')) {
+		if (!part || part === '.') continue;
+		if (part === '..') {
+			if (normalized.length === 0) {
+				escapedRoot = true;
+				if (options.rejectRootEscape) continue;
+			} else {
+				normalized.pop();
+			}
+			continue;
+		}
+		normalized.push(part);
+	}
+
+	return { path: normalized.join('/'), escapedRoot };
+}

packages/ims-cp-core/src/qti3-shared-content.ts

@@ -1,4 +1,9 @@
 import { parse, type HTMLElement, type Node } from 'node-html-parser';
+import {
+	isPackageRelativeHref,
+	resolveCheckedPackagePathFromFile,
+	resolvePackagePathFromFile,
+} from './package-path.js';
 
 export interface AssessmentStimulusRef {
 	identifier: string;
@@ -225,39 +230,12 @@ export function extractCatalogInfoXml(xml: string): string[] {
 }
 
 export function resolveRelativePath(baseHref: string, relativePath: string): string {
-	const baseDir = baseHref.includes('/') ? baseHref.substring(0, baseHref.lastIndexOf('/') + 1) : '';
-	const combined = baseDir + relativePath;
-	const resolved: string[] = [];
-	for (const part of combined.split('/')) {
-		if (!part || part === '.') continue;
-		if (part === '..') {
-			if (resolved.length > 0) resolved.pop();
-		} else {
-			resolved.push(part);
-		}
-	}
-	return resolved.join('/');
-}
-
-function resolveCheckedRelativePath(baseHref: string, relativePath: string): string | null {
-	const baseDir = baseHref.includes('/') ? baseHref.substring(0, baseHref.lastIndexOf('/') + 1) : '';
-	const combined = baseDir + relativePath;
-	const resolved: string[] = [];
-	for (const part of combined.split('/')) {
-		if (!part || part === '.') continue;
-		if (part === '..') {
-			if (resolved.length === 0) return null;
-			resolved.pop();
-		} else {
-			resolved.push(part);
-		}
-	}
-	return resolved.join('/');
+	return resolvePackagePathFromFile(baseHref, relativePath);
 }
 
 function resolveCheckedPackagePath(baseHref: string, href: string): string | null {
 	if (!isPackageRelativeHref(href)) return null;
-	return resolveCheckedRelativePath(baseHref, href);
+	return resolveCheckedPackagePathFromFile(baseHref, href);
 }
 
 function resolvePackageHref(
@@ -320,11 +298,6 @@ function sanitizeStylesheetCss(css: string, validationMessages: string[], resolv
 	return css;
 }
 
-function isPackageRelativeHref(href: string): boolean {
-	const value = href.trim();
-	return Boolean(value) && !value.startsWith('/') && !value.startsWith('//') && !/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(value);
-}
-
 function rewriteHtmlAssetRefs(
 	html: string,
 	baseHref: string,

packages/ims-cp-core/tests/package-path.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from 'bun:test';
+import {
+	dirnamePackagePath,
+	isExternalPackageHref,
+	isPackageRelativeHref,
+	resolveCheckedPackagePathFromFile,
+	resolvePackagePath,
+	resolvePackagePathFromFile,
+} from '../src/package-path';
+
+describe('IMS CP package path resolution', () => {
+	test('normalizes package paths with manifest-style base directories', () => {
+		expect(resolvePackagePath('content/items', './images/../item.xml')).toBe('content/items/item.xml');
+		expect(resolvePackagePath('content/items', '/shared/passage.xml')).toBe('shared/passage.xml');
+		expect(resolvePackagePath('content/items', '..\\assets\\chart.png')).toBe('content/assets/chart.png');
+	});
+
+	test('resolves hrefs relative to source files', () => {
+		expect(resolvePackagePathFromFile('items/item.xml', 'images/chart.png')).toBe('items/images/chart.png');
+		expect(resolvePackagePathFromFile('tests/test.xml', '../items/item.xml')).toBe('items/item.xml');
+		expect(dirnamePackagePath('tests/unit/test.xml')).toBe('tests/unit');
+	});
+
+	test('checked resolution rejects hrefs that escape the package root', () => {
+		expect(resolveCheckedPackagePathFromFile('items/item.xml', '../shared/passage.xml')).toBe('shared/passage.xml');
+		expect(resolveCheckedPackagePathFromFile('item.xml', '../outside.xml')).toBeNull();
+		expect(resolveCheckedPackagePathFromFile('item.xml', 'http://example.com/item.xml')).toBeNull();
+	});
+
+	test('classifies package-relative and external hrefs', () => {
+		expect(isPackageRelativeHref('items/item.xml')).toBe(true);
+		expect(isPackageRelativeHref('/items/item.xml')).toBe(false);
+		expect(isPackageRelativeHref('https://example.com/item.xml')).toBe(false);
+		expect(isExternalPackageHref('#fragment')).toBe(true);
+		expect(isExternalPackageHref('//cdn.example.com/item.xml')).toBe(true);
+	});
+});