Initial module scaffold

2026-04-20 20:07:44 +00:00
commit c3e590e782
11 changed files with 1474 additions and 0 deletions
--- a/scripts/adapters/foundry-runtime.js
+++ b/scripts/adapters/foundry-runtime.js
@@ -0,0 +1,110 @@
+import { analyzeStorage } from "../core/analyzer.js";
+import { isMediaPath, normalizePath } from "../core/path-utils.js";
+
+async function* walkFilePicker(storage, target = "", onProgress = null) {
+  onProgress?.({ phase: "files", label: `Durchsuche ${storage}:${target || "/"}` });
+  const result = await FilePicker.browse(storage, target);
+  for (const file of result.files ?? []) {
+    const path = normalizePath(file);
+    if (!isMediaPath(path)) continue;
+    yield { storage, path };
+  }
+  for (const directory of result.dirs ?? []) {
+    const path = normalizePath(directory);
+    yield* walkFilePicker(storage, path, onProgress);
+  }
+}
+
+async function* listFoundryFiles(onProgress = null) {
+  for (const storage of ["data", "public"]) {
+    if (!game.data.files.storages.includes(storage)) continue;
+    yield* walkFilePicker(storage, "", onProgress);
+  }
+}
+
+function worldCollectionEntries() {
+  if (!game.world) return [];
+  const entries = [];
+  for (const collection of game.collections ?? []) {
+    const docs = Array.from(collection.values?.() ?? []);
+    for (const doc of docs) {
+      entries.push({
+        sourceType: "world-document",
+        sourceScope: {
+          ownerType: "world",
+          ownerId: game.world.id,
+          systemId: game.world.system,
+          subtype: doc.documentName?.toLowerCase() ?? collection.documentName?.toLowerCase() ?? "document"
+        },
+        sourceLabel: `${doc.documentName ?? "Document"} ${doc.id}`,
+        value: doc.toObject ? doc.toObject() : doc
+      });
+    }
+  }
+  return entries;
+}
+
+function packageMetadataEntries() {
+  const entries = [];
+  for (const module of game.modules.values()) {
+    entries.push({
+      sourceType: "module-manifest",
+      sourceScope: { ownerType: "module", ownerId: module.id, subtype: "manifest" },
+      sourceLabel: `module.json ${module.id}`,
+      value: module.toObject ? module.toObject() : module
+    });
+  }
+  if (game.system) {
+    entries.push({
+      sourceType: "system-manifest",
+      sourceScope: { ownerType: "system", ownerId: game.system.id, subtype: "manifest" },
+      sourceLabel: `system.json ${game.system.id}`,
+      value: game.system.toObject ? game.system.toObject() : game.system
+    });
+  }
+  if (game.world) {
+    entries.push({
+      sourceType: "world-manifest",
+      sourceScope: { ownerType: "world", ownerId: game.world.id, systemId: game.world.system, subtype: "manifest" },
+      sourceLabel: `world.json ${game.world.id}`,
+      value: game.world.toObject ? game.world.toObject() : game.world
+    });
+  }
+  return entries;
+}
+
+async function* packagePackEntries(onProgress = null) {
+  for (const pack of game.packs.values()) {
+    const ownerType = pack.metadata.packageType;
+    const ownerId = pack.metadata.packageName;
+    if (!["module", "system"].includes(ownerType) || !ownerId) continue;
+    onProgress?.({ phase: "sources", label: `Lese Paket-Pack ${pack.collection}`, currentSource: pack.collection });
+    const documents = await pack.getDocuments();
+    for (const document of documents) {
+      yield {
+        sourceType: "package-pack-document",
+        sourceScope: {
+          ownerType,
+          ownerId,
+          subtype: `pack:${pack.collection}`
+        },
+        sourceLabel: `${pack.collection} ${document.id}`,
+        value: document.toObject ? document.toObject() : document
+      };
+    }
+  }
+}
+
+async function* listFoundrySources(onProgress = null) {
+  yield* worldCollectionEntries();
+  yield* packageMetadataEntries();
+  yield* packagePackEntries(onProgress);
+}
+
+export async function runRuntimeAnalysis({ onProgress }={}) {
+  return analyzeStorage({
+    listFiles: () => listFoundryFiles(onProgress),
+    listSources: () => listFoundrySources(onProgress),
+    onProgress
+  });
+}
--- a/scripts/apps/audit-report-app.js
+++ b/scripts/apps/audit-report-app.js
@@ -0,0 +1,421 @@
+export class StorageAuditReportApp extends foundry.applications.api.ApplicationV2 {
+  static DEFAULT_OPTIONS = {
+    id: "kosmos-storage-audit-report",
+    classes: ["kosmos-storage-audit"],
+    tag: "div",
+    actions: {
+      runAnalysis: StorageAuditReportApp.#onRunAnalysis,
+      toggleShowAll: StorageAuditReportApp.#onToggleShowAll
+    },
+    window: {
+      title: "Kosmos Storage Audit",
+      icon: "fa-solid fa-broom-ball",
+      resizable: true
+    },
+    position: {
+      width: 760,
+      height: 680
+    }
+  };
+
+  #analysis = null;
+  #loading = false;
+  #showAll = false;
+  #progress = null;
+
+  async _prepareContext() {
+    const findings = this.#analysis?.findings ?? [];
+    const visibleFindings = this.#showAll ? findings : findings.filter(f => f.severity !== "info");
+    const groupedFindings = groupFindings(visibleFindings);
+    return {
+      loading: this.#loading,
+      hasAnalysis: !!this.#analysis,
+      showAll: this.#showAll,
+      progress: this.#progress,
+      summary: this.#summarize(this.#analysis),
+      groupedFindings,
+      findings: visibleFindings.slice(0, 100)
+    };
+  }
+
+  async _renderHTML(context) {
+    const container = document.createElement("div");
+    container.className = "storage-audit";
+    container.innerHTML = `
+      <section class="storage-audit__hero">
+        <div>
+          <h2>Kosmos Storage Audit</h2>
+          <p>Prueft Medienreferenzen und markiert primaer benutzerrelevante Risiken in den Foundry-Roots <code>data</code> und <code>public</code>.</p>
+          <p>Orphans werden bewusst nicht global fuer den gesamten <code>data</code>-Root behauptet, sondern nur in klar weltlokalen oder explizit riskanten Bereichen.</p>
+          <p>Weltverweise auf Modul- oder Systemassets gelten nicht pauschal als Problem. Relevant sind vor allem Ziele, die im owning Paket selbst nicht sichtbar referenziert werden.</p>
+        </div>
+        <div class="storage-audit__actions">
+          <button type="button" class="button" data-action="runAnalysis" ${context.loading ? "disabled" : ""}>
+            <i class="fa-solid fa-magnifying-glass"></i>
+            <span>${context.loading ? "Analysiere..." : "Analyse Starten"}</span>
+          </button>
+          <button type="button" class="button" data-action="toggleShowAll" ${context.hasAnalysis ? "" : "disabled"}>
+            <i class="fa-solid fa-filter"></i>
+            <span>${context.showAll ? "Nur Warnungen" : "Alle Findings"}</span>
+          </button>
+        </div>
+      </section>
+      ${renderProgress(context.progress, context.loading)}
+      ${renderSummary(context.summary)}
+      ${renderGroupedFindingList(context.groupedFindings, context.hasAnalysis, context.loading, context.showAll)}
+      ${renderFindingList(context.findings, context.hasAnalysis, context.loading, context.showAll)}
+    `;
+    return container;
+  }
+
+  _replaceHTML(result, content) {
+    content.replaceChildren(result);
+  }
+
+  async runAnalysis() {
+    this.#loading = true;
+    this.#progress = {
+      phase: "start",
+      label: "Initialisiere Analyse",
+      files: 0,
+      sources: 0,
+      references: 0,
+      findings: 0,
+      currentSource: null
+    };
+    await this.render({ force: true });
+    try {
+      const api = game.modules.get("kosmos-storage-audit")?.api;
+      this.#analysis = await api.runRuntimeAnalysis({
+        onProgress: update => this.#updateProgress(update)
+      });
+      const count = this.#analysis.findings.length;
+      ui.notifications.info(`Kosmos Storage Audit abgeschlossen: ${count} Findings.`);
+    } catch (error) {
+      console.error("kosmos-storage-audit | analysis failed", error);
+      ui.notifications.error(`Kosmos Storage Audit fehlgeschlagen: ${error.message}`);
+    } finally {
+      this.#loading = false;
+      await this.render({ force: true });
+    }
+  }
+
+  toggleShowAll() {
+    this.#showAll = !this.#showAll;
+    return this.render({ force: true });
+  }
+
+  #summarize(analysis) {
+    if (!analysis) return null;
+    const bySeverity = { high: 0, warning: 0, info: 0 };
+    const byKind = {};
+    const grouped = {
+      brokenReferences: 0,
+      packageReferences: 0,
+      orphans: 0
+    };
+    for (const finding of analysis.findings) {
+      bySeverity[finding.severity] = (bySeverity[finding.severity] ?? 0) + 1;
+      byKind[finding.kind] = (byKind[finding.kind] ?? 0) + 1;
+    }
+    grouped.brokenReferences = new Set(
+      analysis.findings.filter(f => f.kind === "broken-reference").map(f => f.target.locator ?? formatTarget(f.target))
+    ).size;
+    grouped.packageReferences = new Set(
+      analysis.findings.filter(f => f.kind === "non-package-to-package-reference").map(f => f.target.locator ?? formatTarget(f.target))
+    ).size;
+    grouped.orphans = analysis.findings.filter(f => f.kind === "orphan-file").length;
+    return {
+      files: analysis.files.length,
+      references: analysis.references.length,
+      findings: analysis.findings.length,
+      bySeverity,
+      byKind,
+      grouped
+    };
+  }
+
+  #updateProgress(update) {
+    this.#progress = {
+      ...(this.#progress ?? {}),
+      ...update
+    };
+    this.render({ force: true });
+  }
+
+  static #onRunAnalysis(_event, _button) {
+    return this.runAnalysis();
+  }
+
+  static #onToggleShowAll(_event, _button) {
+    return this.toggleShowAll();
+  }
+}
+
+function renderProgress(progress, loading) {
+  if (!loading || !progress) return "";
+  return `
+    <section class="storage-audit__progress">
+      <div class="storage-audit__progress-bar">
+        <div class="storage-audit__progress-fill phase-${escapeHtml(progress.phase ?? "start")}"></div>
+      </div>
+      <div class="storage-audit__progress-meta">
+        <strong>${escapeHtml(progress.label ?? "Analysiere")}</strong>
+        <span>Dateien: ${progress.files ?? 0}</span>
+        <span>Quellen: ${progress.sources ?? 0}</span>
+        <span>Referenzen: ${progress.references ?? 0}</span>
+        ${progress.findings != null ? `<span>Findings: ${progress.findings}</span>` : ""}
+      </div>
+      ${progress.currentSource ? `<p class="storage-audit__progress-source">Aktuell: ${escapeHtml(progress.currentSource)}</p>` : ""}
+    </section>
+  `;
+}
+
+function renderSummary(summary) {
+  if (!summary) {
+    return `
+      <section class="storage-audit__summary">
+        <p>Noch keine Analyse ausgefuehrt.</p>
+      </section>
+    `;
+  }
+
+  const kindLines = Object.entries(summary.byKind)
+    .sort((a, b) => b[1] - a[1])
+    .map(([kind, count]) => `<li><code>${kind}</code><span>${count}</span></li>`)
+    .join("");
+
+  return `
+    <section class="storage-audit__summary">
+      <div class="storage-audit__stats">
+        <article><span>Dateien</span><strong>${summary.files}</strong></article>
+        <article><span>Referenzen</span><strong>${summary.references}</strong></article>
+        <article><span>Findings</span><strong>${summary.findings}</strong></article>
+        <article><span>High</span><strong>${summary.bySeverity.high}</strong></article>
+        <article><span>Warning</span><strong>${summary.bySeverity.warning}</strong></article>
+      </div>
+      <div class="storage-audit__kinds">
+        <h3>Findings nach Typ</h3>
+        <ul>${kindLines || "<li><span>Keine Findings</span><span>0</span></li>"}</ul>
+      </div>
+      <div class="storage-audit__kinds">
+        <h3>Arbeitsbloecke</h3>
+        <ul>
+          <li><span>Deduplizierte fehlende Ziele</span><span>${summary.grouped?.brokenReferences ?? 0}</span></li>
+          <li><span>Unverankerte Paketziele</span><span>${summary.grouped?.packageReferences ?? 0}</span></li>
+          <li><span>Orphan-Kandidaten</span><span>${summary.grouped?.orphans ?? 0}</span></li>
+        </ul>
+      </div>
+    </section>
+  `;
+}
+
+function renderGroupedFindingList(groupedFindings, hasAnalysis, loading, showAll) {
+  if (loading || !hasAnalysis) return "";
+
+  const sections = [];
+  if (groupedFindings.nonPackageToPackage.length) {
+    sections.push(renderGroupedSection(
+      "Unverankerte Paketziele",
+      "Diese Ziele liegen in Modul- oder Systemordnern, werden aus Weltdaten referenziert, sind im owning Paket selbst aber derzeit nicht als Referenz sichtbar.",
+      groupedFindings.nonPackageToPackage,
+      group => `
+        <article class="storage-audit__finding severity-${group.severity}">
+          <header>
+            <span class="storage-audit__severity">${group.severity}</span>
+            <code>${group.kind}</code>
+            <strong>${group.count} Referenzen</strong>
+          </header>
+          <p><code>${escapeHtml(group.target)}</code></p>
+          <p>${escapeHtml(group.reason)}</p>
+          <dl>
+            <div><dt>Owner-Paket</dt><dd><code>${escapeHtml(group.ownerLabel)}</code></dd></div>
+            <div><dt>Bewertung</dt><dd>${escapeHtml(group.explanation)}</dd></div>
+          </dl>
+          <p class="storage-audit__recommendation">${escapeHtml(group.recommendation)}</p>
+          ${renderSampleSources(group.sources)}
+        </article>
+      `
+    ));
+  }
+
+  if (groupedFindings.brokenReferences.length) {
+    sections.push(renderGroupedSection(
+      "Kaputte Ziele",
+      "Diese Dateien fehlen, werden aber weiterhin referenziert.",
+      groupedFindings.brokenReferences,
+      group => `
+        <article class="storage-audit__finding severity-${group.severity}">
+          <header>
+            <span class="storage-audit__severity">${group.severity}</span>
+            <code>${group.kind}</code>
+            <strong>${group.count} Referenzen</strong>
+          </header>
+          <p><code>${escapeHtml(group.target)}</code></p>
+          <p>${escapeHtml(group.reason)}</p>
+          <p class="storage-audit__recommendation">${escapeHtml(group.recommendation)}</p>
+          ${renderSampleSources(group.sources)}
+        </article>
+      `
+    ));
+  }
+
+  if (showAll && groupedFindings.orphans.length) {
+    sections.push(renderGroupedSection(
+      "Orphan-Kandidaten",
+      "Diese Dateien haben im aktuellen Analysekontext keine eingehende Referenz.",
+      groupedFindings.orphans,
+      group => `
+        <article class="storage-audit__finding severity-${group.severity}">
+          <header>
+            <span class="storage-audit__severity">${group.severity}</span>
+            <code>${group.kind}</code>
+          </header>
+          <p><code>${escapeHtml(group.target)}</code></p>
+          <p>${escapeHtml(group.reason)}</p>
+          <p class="storage-audit__recommendation">${escapeHtml(group.recommendation)}</p>
+        </article>
+      `
+    ));
+  }
+
+  if (!sections.length) {
+    return `
+      <section class="storage-audit__grouped">
+        <div class="storage-audit__group-header">
+          <h3>Arbeitsansicht</h3>
+          <p>Keine gruppierten ${showAll ? "" : "warnenden "}Findings vorhanden.</p>
+        </div>
+      </section>
+    `;
+  }
+
+  return `<section class="storage-audit__grouped">${sections.join("")}</section>`;
+}
+
+function renderGroupedSection(title, description, groups, renderGroup) {
+  const items = groups.slice(0, 12).map(renderGroup).join("");
+  return `
+    <section class="storage-audit__group">
+      <div class="storage-audit__group-header">
+        <h3>${title}</h3>
+        <p>${description}</p>
+      </div>
+      <div class="storage-audit__list">${items}</div>
+    </section>
+  `;
+}
+
+function renderFindingList(findings, hasAnalysis, loading, showAll) {
+  if (loading) {
+    return `<section class="storage-audit__list"><p>Analyse laeuft...</p></section>`;
+  }
+  if (!hasAnalysis) {
+    return `<section class="storage-audit__list"><p>Die Analyse kann direkt aus dieser Ansicht gestartet werden.</p></section>`;
+  }
+  if (!findings.length) {
+    return `<section class="storage-audit__list"><p>Keine ${showAll ? "" : "warnenden "}Findings gefunden.</p></section>`;
+  }
+
+  const items = findings.map(finding => `
+    <article class="storage-audit__finding severity-${finding.severity}">
+      <header>
+        <span class="storage-audit__severity">${finding.severity}</span>
+        <code>${finding.kind}</code>
+      </header>
+      <p>${escapeHtml(finding.reason)}</p>
+      <dl>
+        <div><dt>Ziel</dt><dd><code>${escapeHtml(finding.target.locator ?? `${finding.target.storage}:${finding.target.path}`)}</code></dd></div>
+        ${finding.source ? `<div><dt>Quelle</dt><dd>${escapeHtml(finding.source.sourceLabel)}</dd></div>` : ""}
+      </dl>
+      <p class="storage-audit__recommendation">${escapeHtml(finding.recommendation)}</p>
+    </article>
+  `).join("");
+
+  return `
+    <section class="storage-audit__list storage-audit__list--raw">
+      <h3>Einzelfaelle</h3>
+      ${items}
+    </section>
+  `;
+}
+
+function renderSampleSources(sources) {
+  if (!sources.length) return "";
+  const rows = sources.map(source => `<li>${escapeHtml(source)}</li>`).join("");
+  return `<div class="storage-audit__samples"><span>Beispiele</span><ul>${rows}</ul></div>`;
+}
+
+function groupFindings(findings) {
+  return {
+    brokenReferences: groupByTarget(findings.filter(f => f.kind === "broken-reference")),
+    nonPackageToPackage: groupByTarget(findings.filter(f => f.kind === "non-package-to-package-reference")),
+    orphans: findings
+      .filter(f => f.kind === "orphan-file")
+      .sort(compareFindings)
+      .map(finding => ({
+        kind: finding.kind,
+        severity: finding.severity,
+        target: finding.target.locator ?? formatTarget(finding.target),
+        reason: finding.reason,
+        recommendation: finding.recommendation
+      }))
+  };
+}
+
+function groupByTarget(findings) {
+  const grouped = new Map();
+  for (const finding of findings) {
+    const target = finding.target.locator ?? formatTarget(finding.target);
+    const ownerLabel = deriveOwnerLabel(target);
+    const current = grouped.get(target) ?? {
+      kind: finding.kind,
+      severity: finding.severity,
+      target,
+      count: 0,
+      ownerLabel,
+      explanation: "Weltdaten zeigen auf ein Paketasset, fuer das in Manifesten und Paket-Packs keine sichtbare Eigenreferenz gefunden wurde.",
+      reason: finding.reason,
+      recommendation: finding.recommendation,
+      sources: new Set()
+    };
+    current.count += 1;
+    if (finding.severity === "high") current.severity = "high";
+    if (finding.source?.sourceLabel) current.sources.add(finding.source.sourceLabel);
+    grouped.set(target, current);
+  }
+  return [...grouped.values()]
+    .map(group => ({ ...group, sources: [...group.sources].slice(0, 5) }))
+    .sort((a, b) => compareSeverity(a.severity, b.severity) || (b.count - a.count) || a.target.localeCompare(b.target));
+}
+
+function deriveOwnerLabel(target) {
+  const [, path] = String(target).split(":", 2);
+  const parts = (path ?? "").split("/");
+  if ((parts[0] === "modules") || (parts[0] === "systems")) {
+    return `${parts[0]}:${parts[1] ?? "unknown"}`;
+  }
+  return "unbekannt";
+}
+
+function compareFindings(a, b) {
+  return compareSeverity(a.severity, b.severity)
+    || formatTarget(a.target).localeCompare(formatTarget(b.target));
+}
+
+function compareSeverity(a, b) {
+  const order = { high: 0, warning: 1, info: 2 };
+  return (order[a] ?? 9) - (order[b] ?? 9);
+}
+
+function formatTarget(target) {
+  return target.locator ?? `${target.storage}:${target.path}`;
+}
+
+function escapeHtml(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/\"/g, "&quot;");
+}
--- a/scripts/core/analyzer.js
+++ b/scripts/core/analyzer.js
@@ -0,0 +1,60 @@
+import { buildFindings, createFileRecord } from "./finding-engine.js";
+import { extractReferencesFromValue } from "./reference-extractor.js";
+import { createFileLocator } from "./path-utils.js";
+
+export async function analyzeStorage({ listFiles, listSources, onProgress }={}) {
+  const files = [];
+  let fileCount = 0;
+  let sourceCount = 0;
+  let referenceCount = 0;
+
+  onProgress?.({ phase: "files", label: "Scanne Dateien", files: 0, sources: 0, references: 0 });
+  for await (const entry of listFiles()) {
+    files.push(createFileRecord(createFileLocator(entry.storage, entry.path), entry.size ?? null));
+    fileCount += 1;
+    if ((fileCount % 100) === 0) {
+      onProgress?.({ phase: "files", label: "Scanne Dateien", files: fileCount, sources: sourceCount, references: referenceCount });
+      await yieldToUI();
+    }
+  }
+
+  const references = [];
+  onProgress?.({ phase: "sources", label: "Lese Referenzen", files: fileCount, sources: 0, references: 0 });
+  for await (const source of listSources()) {
+    sourceCount += 1;
+    const extracted = extractReferencesFromValue(source.value, {
+      sourceType: source.sourceType,
+      sourceScope: source.sourceScope,
+      sourceLabel: source.sourceLabel
+    });
+    references.push(...extracted);
+    referenceCount += extracted.length;
+    if ((sourceCount % 50) === 0) {
+      onProgress?.({
+        phase: "sources",
+        label: "Lese Referenzen",
+        files: fileCount,
+        sources: sourceCount,
+        references: referenceCount,
+        currentSource: source.sourceLabel
+      });
+      await yieldToUI();
+    }
+  }
+
+  onProgress?.({ phase: "findings", label: "Klassifiziere Findings", files: fileCount, sources: sourceCount, references: referenceCount });
+  const findings = buildFindings({ files, references });
+  onProgress?.({
+    phase: "done",
+    label: "Analyse abgeschlossen",
+    files: fileCount,
+    sources: sourceCount,
+    references: referenceCount,
+    findings: findings.length
+  });
+  return { files, references, findings };
+}
+
+async function yieldToUI() {
+  await new Promise(resolve => setTimeout(resolve, 0));
+}
--- a/scripts/core/finding-engine.js
+++ b/scripts/core/finding-engine.js
@@ -0,0 +1,154 @@
+import { classifyRisk, detectMediaKind, inferOwnerHint, isCorePublicPath, isStorageAreaPath } from "./path-utils.js";
+
+function compareOwner(sourceScope, targetOwner) {
+  if (!sourceScope) return "unknown";
+  if ((sourceScope.ownerType === "world") && (targetOwner.ownerType === "system") && (sourceScope.systemId === targetOwner.ownerId)) {
+    return "same-system";
+  }
+  if ((sourceScope.ownerType === "world") && (targetOwner.ownerType === "public") &&
+      ["cards", "icons", "nue", "sounds", "ui"].includes(targetOwner.ownerId)) {
+    return "core-public";
+  }
+  if ((sourceScope.ownerType === "module") && (targetOwner.ownerType === "module")) {
+    return sourceScope.ownerId === targetOwner.ownerId ? "same-package" : "foreign-module";
+  }
+  if ((sourceScope.ownerType === "system") && (targetOwner.ownerType === "system")) {
+    return sourceScope.ownerId === targetOwner.ownerId ? "same-package" : "cross-package";
+  }
+  if ((sourceScope.ownerType === "world") && (targetOwner.ownerType === "world")) {
+    return sourceScope.ownerId === targetOwner.ownerId ? "same-world" : "cross-world";
+  }
+  if ((sourceScope.ownerType === "world") && ((targetOwner.ownerType === "module") || (targetOwner.ownerType === "system"))) {
+    return "non-package-to-package";
+  }
+  if ((sourceScope.ownerType === "world") && (targetOwner.ownerType === "public")) {
+    return "risky-public";
+  }
+  if (((sourceScope.ownerType === "module") || (sourceScope.ownerType === "system")) &&
+      ((targetOwner.ownerType === "module") || (targetOwner.ownerType === "system")) &&
+      ((sourceScope.ownerType !== targetOwner.ownerType) || (sourceScope.ownerId !== targetOwner.ownerId))) {
+    return "cross-package";
+  }
+  return "allowed";
+}
+
+export function buildFindings({ files, references }) {
+  const fileByLocator = new Map(files.map(file => [file.locator, file]));
+  const refsByLocator = new Map();
+  const findings = [];
+
+  for (const reference of references) {
+    const normalized = reference.normalized;
+    if (!normalized) continue;
+    const bucket = refsByLocator.get(normalized.locator) ?? [];
+    bucket.push(reference);
+    refsByLocator.set(normalized.locator, bucket);
+  }
+
+  for (const reference of references) {
+    const normalized = reference.normalized;
+    if (!normalized) continue;
+
+    const file = fileByLocator.get(normalized.locator);
+    if (!file) {
+      if (reference.sourceScope?.ownerType !== "world") continue;
+      findings.push({
+        kind: "broken-reference",
+        severity: reference.sourceScope?.ownerType === "world" ? "high" : "warning",
+        target: normalized,
+        source: reference,
+        reason: `Referenced file ${normalized.locator} does not exist in the scanned roots.`,
+        recommendation: "Check whether the file was moved, deleted, or should be copied into a stable location.",
+        confidence: "high"
+      });
+      continue;
+    }
+
+    const ownerRelation = compareOwner(reference.sourceScope, file.ownerHint);
+    if (ownerRelation === "non-package-to-package") {
+      if (isAnchoredInOwningPackage(file, refsByLocator.get(normalized.locator) ?? [])) continue;
+      findings.push({
+        kind: "non-package-to-package-reference",
+        severity: "high",
+        target: normalized,
+        source: reference,
+        reason: `${reference.sourceScope.ownerType}:${reference.sourceScope.ownerId} references package-owned storage ${normalized.locator}, but the asset is not visibly referenced by its owning package.`,
+        recommendation: "Review whether the file was manually placed into the package folder. If the package does not use it itself, prefer moving it into user-controlled storage.",
+        confidence: "high"
+      });
+    } else if (ownerRelation === "risky-public") {
+      if (reference.sourceScope?.ownerType !== "world") continue;
+      findings.push({
+        kind: "risky-public-reference",
+        severity: "high",
+        target: normalized,
+        source: reference,
+        reason: `${reference.sourceScope.ownerType}:${reference.sourceScope.ownerId} references release-public storage ${normalized.locator}.`,
+        recommendation: "Prefer copying the asset into world or user-controlled storage.",
+        confidence: "high"
+      });
+    }
+  }
+
+  for (const file of files) {
+    if (detectMediaKind(file.path) === "other") continue;
+    const refs = refsByLocator.get(file.locator) ?? [];
+    if (refs.length) continue;
+    if (!shouldReportOrphan(file, references)) continue;
+
+    const severity = (file.riskClass === "package-module") || (file.riskClass === "package-system") || (file.riskClass === "release-public")
+      ? "warning"
+      : "info";
+
+    findings.push({
+      kind: "orphan-file",
+      severity,
+      target: file,
+      source: null,
+      reason: `No incoming media reference was found for ${file.locator}.`,
+      recommendation: severity === "warning"
+        ? "Review whether the file is safe to remove or should be moved into a stable storage location."
+        : "Review whether the file is intentionally kept as reserve content.",
+      confidence: "medium"
+    });
+  }
+
+  return findings;
+}
+
+function isAnchoredInOwningPackage(file, references) {
+  const ownerType = file.ownerHint.ownerType;
+  const ownerId = file.ownerHint.ownerId;
+  if (!["module", "system"].includes(ownerType) || !ownerId) return false;
+  return references.some(reference =>
+    (reference.sourceScope?.ownerType === ownerType) &&
+    (reference.sourceScope?.ownerId === ownerId)
+  );
+}
+
+function shouldReportOrphan(file, references) {
+  if (file.riskClass === "stable-world") {
+    const worldId = file.ownerHint.ownerId;
+    return references.some(reference => reference.sourceScope?.ownerType === "world" && reference.sourceScope.ownerId === worldId);
+  }
+  if ((file.riskClass === "package-module") || (file.riskClass === "package-system")) {
+    return isStorageAreaPath(file);
+  }
+  if (file.riskClass === "release-public") {
+    return !isCorePublicPath(file);
+  }
+  return false;
+}
+
+export function createFileRecord(locator, size = null) {
+  return {
+    ...locator,
+    basename: locator.path.split("/").pop() ?? locator.path,
+    extension: locator.path.includes(".") ? locator.path.split(".").pop().toLowerCase() : "",
+    size,
+    mediaKind: detectMediaKind(locator.path),
+    ownerHint: inferOwnerHint(locator),
+    riskClass: classifyRisk(locator),
+    exists: true
+  };
+}
--- a/scripts/core/path-utils.js
+++ b/scripts/core/path-utils.js
@@ -0,0 +1,120 @@
+export const RELEASE_PREFIXES = new Set(["canvas", "cards", "docs", "fonts", "icons", "lang", "nue", "scripts", "sounds", "toolclips", "tours", "ui"]);
+const DATA_PREFIXES = new Set(["assets", "modules", "systems", "worlds"]);
+const MEDIA_EXTENSIONS = {
+  image: new Set(["avif", "gif", "jpeg", "jpg", "png", "svg", "webp"]),
+  video: new Set(["m4v", "mkv", "mov", "mp4", "mpeg", "mpg", "webm"]),
+  audio: new Set(["flac", "m4a", "mid", "midi", "mp3", "ogg", "opus", "wav", "webm"])
+};
+
+export function normalizePath(path) {
+  const normalized = String(path ?? "")
+    .replace(/\\/g, "/")
+    .replace(/^[./]+/, "")
+    .replace(/^\/+/, "")
+    .replace(/\/{2,}/g, "/")
+    .trim();
+  try {
+    return decodeURI(normalized);
+  } catch {
+    return normalized;
+  }
+}
+
+export function splitResourceSuffix(path) {
+  const [withoutHash] = String(path ?? "").split("#", 1);
+  const [cleanPath] = withoutHash.split("?", 1);
+  return cleanPath;
+}
+
+export function parseStoragePath(rawValue) {
+  if (typeof rawValue !== "string") return null;
+  const trimmed = rawValue.trim();
+  if (!trimmed) return null;
+  if (/^(?:https?:|data:|blob:)/i.test(trimmed)) return null;
+
+  const clean = normalizePath(splitResourceSuffix(trimmed));
+  if (!clean) return null;
+
+  const first = clean.split("/", 1)[0];
+  let storage = null;
+  if (DATA_PREFIXES.has(first)) storage = "data";
+  else if (RELEASE_PREFIXES.has(first)) storage = "public";
+  if (!storage) return null;
+
+  return {
+    storage,
+    path: clean,
+    locator: `${storage}:${clean}`
+  };
+}
+
+export function getExtension(path) {
+  const clean = normalizePath(path);
+  const index = clean.lastIndexOf(".");
+  return index === -1 ? "" : clean.slice(index + 1).toLowerCase();
+}
+
+export function detectMediaKind(path) {
+  const ext = getExtension(path);
+  for (const [kind, extensions] of Object.entries(MEDIA_EXTENSIONS)) {
+    if (extensions.has(ext)) return kind;
+  }
+  return "other";
+}
+
+export function isMediaPath(path) {
+  return detectMediaKind(path) !== "other";
+}
+
+export function classifyRisk(locator) {
+  const parts = locator.path.split("/");
+  if (locator.storage === "public") return "release-public";
+  if (parts[0] === "modules") return "package-module";
+  if (parts[0] === "systems") return "package-system";
+  if (parts[0] === "assets") return "stable-user";
+  if (parts[0] === "worlds") return "stable-world";
+  return locator.storage === "data" ? "stable-user" : "unknown";
+}
+
+export function inferOwnerHint(locator) {
+  const parts = locator.path.split("/");
+  if (locator.storage === "public") {
+    return { ownerType: "public", ownerId: parts[0] ?? null };
+  }
+  if (parts[0] === "assets") {
+    return { ownerType: "user", ownerId: null };
+  }
+  if ((parts[0] === "worlds") && parts[1]) {
+    return { ownerType: "world", ownerId: parts[1] };
+  }
+  if ((parts[0] === "modules") && parts[1]) {
+    return { ownerType: "module", ownerId: parts[1] };
+  }
+  if ((parts[0] === "systems") && parts[1]) {
+    return { ownerType: "system", ownerId: parts[1] };
+  }
+  if (locator.storage === "data") {
+    return { ownerType: "user", ownerId: parts[0] ?? null };
+  }
+  return { ownerType: "unknown", ownerId: null };
+}
+
+export function isStorageAreaPath(locator) {
+  const parts = locator.path.split("/");
+  return ((parts[0] === "modules") || (parts[0] === "systems")) && (parts[2] === "storage");
+}
+
+export function isCorePublicPath(locator) {
+  if (locator.storage !== "public") return false;
+  const parts = locator.path.split("/");
+  return RELEASE_PREFIXES.has(parts[0] ?? "");
+}
+
+export function createFileLocator(storage, path) {
+  const cleanPath = normalizePath(path);
+  return {
+    storage,
+    path: cleanPath,
+    locator: `${storage}:${cleanPath}`
+  };
+}
--- a/scripts/core/reference-extractor.js
+++ b/scripts/core/reference-extractor.js
@@ -0,0 +1,102 @@
+import { createFileLocator, isMediaPath, normalizePath, parseStoragePath } from "./path-utils.js";
+
+const ATTRIBUTE_PATTERNS = [
+  /\b(?:src|href|poster)\s*=\s*["']([^"'<>]+)["']/gi,
+  /url\(\s*["']?([^"')]+)["']?\s*\)/gi
+];
+
+export function collectStringCandidates(value, visit) {
+  if (typeof value === "string") {
+    visit(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) collectStringCandidates(entry, visit);
+    return;
+  }
+  if ((value !== null) && (typeof value === "object")) {
+    for (const entry of Object.values(value)) collectStringCandidates(entry, visit);
+  }
+}
+
+export function extractReferencesFromValue(value, source) {
+  const references = [];
+  collectStringCandidates(value, candidate => {
+    const direct = resolveReference(candidate, source);
+    if (direct && isMediaPath(direct.path)) {
+      references.push({
+        sourceType: source.sourceType,
+        sourceScope: source.sourceScope,
+        sourceLabel: source.sourceLabel,
+        rawValue: candidate,
+        normalized: {
+          ...direct,
+          targetKind: "local-file"
+        }
+      });
+    }
+
+    for (const pattern of ATTRIBUTE_PATTERNS) {
+      pattern.lastIndex = 0;
+      let match;
+      while ((match = pattern.exec(candidate))) {
+        const nested = resolveReference(match[1], source);
+        if (!nested || !isMediaPath(nested.path)) continue;
+        references.push({
+          sourceType: source.sourceType,
+          sourceScope: source.sourceScope,
+          sourceLabel: source.sourceLabel,
+          rawValue: match[1],
+          normalized: {
+            ...nested,
+            targetKind: "local-file"
+          }
+        });
+      }
+    }
+  });
+  return dedupeReferences(references);
+}
+
+function resolveReference(rawValue, source) {
+  const direct = parseStoragePath(rawValue);
+  if (direct) return direct;
+  return resolvePackageRelativeReference(rawValue, source);
+}
+
+function resolvePackageRelativeReference(rawValue, source) {
+  if (typeof rawValue !== "string") return null;
+  if (/^(?:https?:|data:|blob:)/i.test(rawValue.trim())) return null;
+  const path = normalizePath(rawValue);
+  if (!path || !path.includes("/")) return null;
+
+  const ownerType = source.sourceScope?.ownerType;
+  const ownerId = source.sourceScope?.ownerId;
+  if (!ownerType || !ownerId) return null;
+
+  if (ownerType === "module") {
+    return createFileLocator("data", `modules/${ownerId}/${path}`);
+  }
+  if (ownerType === "system") {
+    return createFileLocator("data", `systems/${ownerId}/${path}`);
+  }
+  if (ownerType === "world") {
+    return createFileLocator("data", path);
+  }
+  return null;
+}
+
+function dedupeReferences(references) {
+  const seen = new Set();
+  return references.filter(reference => {
+    const key = [
+      reference.sourceType,
+      reference.sourceLabel,
+      reference.normalized?.locator ?? "",
+      reference.rawValue
+    ].join("|");
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
--- a/scripts/main.js
+++ b/scripts/main.js
@@ -0,0 +1,22 @@
+import { runRuntimeAnalysis } from "./adapters/foundry-runtime.js";
+import { StorageAuditReportApp } from "./apps/audit-report-app.js";
+
+Hooks.once("init", () => {
+  console.log("kosmos-storage-audit | init");
+  game.settings.registerMenu("kosmos-storage-audit", "report", {
+    name: "Kosmos Storage Audit",
+    label: "Open Report",
+    hint: "Run the storage audit and inspect prioritized findings.",
+    icon: "fa-solid fa-broom-ball",
+    type: StorageAuditReportApp,
+    restricted: true
+  });
+  game.modules.get("kosmos-storage-audit").api = {
+    runRuntimeAnalysis,
+    StorageAuditReportApp
+  };
+});
+
+Hooks.once("ready", () => {
+  console.log("kosmos-storage-audit | ready");
+});