pkgviz 0.7.7 → 0.8.1

package/src/features/audit/adapters/inbound/react/CycleInspector.tsx

@@ -0,0 +1,116 @@
+'use client';
+import { XIcon } from 'lucide-react';
+import React from 'react';
+
+import { t } from '@/i18n/i18n';
+import type { CycleEdgeEvidence } from '@/types/audit';
+import type { CycleInspection } from '@/types/auditVisualization';
+
+/*** Renders detailed cycle evidence outside the constrained settings sidebar. */
+export function CycleInspector({ inspection, onClose }: CycleInspectorProps) {
+  return (
+    <aside className="absolute top-4 right-4 z-20 w-[24rem] max-w-[calc(100%-2rem)] rounded-lg border border-neutral-200 bg-white/95 shadow-xl backdrop-blur dark:border-neutral-700 dark:bg-neutral-950/95">
+      <InspectorHeader inspection={inspection} onClose={onClose} />
+      <div className="max-h-[60vh] overflow-y-auto p-4">
+        <section>
+          <h4 className="text-xs font-semibold uppercase tracking-wide text-neutral-500">
+            {t('audit.cyclePath')}
+          </h4>
+          <code className="mt-2 block break-words text-xs leading-5">
+            {inspection.cycle.packages.join(' → ')}
+          </code>
+        </section>
+        <CycleEvidence edges={inspection.cycle.edges} />
+      </div>
+    </aside>
+  );
+}
+
+/*** Renders cycle identity and summary metadata. */
+function InspectorHeader({ inspection, onClose }: CycleInspectorProps) {
+  const packageCount = new Set(inspection.cycle.packages).size;
+
+  return (
+    <header className="flex items-start gap-3 border-b border-neutral-200 px-4 py-3 dark:border-neutral-800">
+      <span
+        aria-hidden="true"
+        className="mt-1 h-2.5 w-2.5 shrink-0 rounded-full"
+        style={{ backgroundColor: inspection.color }}
+      />
+      <div className="min-w-0 flex-1">
+        <h3 className="text-sm font-semibold">{inspection.label}</h3>
+        <p className="mt-0.5 text-xs text-neutral-500 dark:text-neutral-400">
+          {packageCount} {t('audit.packages')} · {inspection.cycle.edges.length}{' '}
+          {t('audit.dependencyEdges')}
+        </p>
+      </div>
+      <button
+        type="button"
+        aria-label={t('audit.closeInspector')}
+        onClick={onClose}
+        className="rounded p-1 text-neutral-500 hover:bg-neutral-100 hover:text-neutral-900 dark:hover:bg-neutral-800 dark:hover:text-neutral-100"
+      >
+        <XIcon size={16} />
+      </button>
+    </header>
+  );
+}
+
+/*** Renders collapsible evidence for every directed edge in the cycle. */
+function CycleEvidence({ edges }: { readonly edges: readonly CycleEdgeEvidence[] }) {
+  return (
+    <section className="mt-4">
+      <h4 className="text-xs font-semibold uppercase tracking-wide text-neutral-500">
+        {t('audit.dependencyEvidence')}
+      </h4>
+      <div className="mt-2 space-y-2">
+        {edges.map((edge, index) => (
+          <EvidenceEdge edge={edge} index={index} key={edge.from + '→' + edge.to + ':' + index} />
+        ))}
+      </div>
+    </section>
+  );
+}
+
+/*** Renders one directed dependency edge and its source/import evidence. */
+function EvidenceEdge({ edge, index }: EvidenceEdgeProps) {
+  return (
+    <details className="rounded border border-neutral-200 bg-neutral-50 px-3 py-2 text-xs dark:border-neutral-800 dark:bg-neutral-900">
+      <summary className="cursor-pointer font-medium">
+        {index + 1}. {edge.from} → {edge.to}
+      </summary>
+      <div className="mt-2 space-y-1 text-[11px] text-neutral-500 dark:text-neutral-400">
+        {edge.via.length === 0
+          ? t('audit.noEvidence')
+          : edge.via.map((evidence, evidenceIndex) => (
+              <div
+                key={
+                  evidence.filePath +
+                  ':' +
+                  evidence.fileClass +
+                  ':' +
+                  evidence.importName +
+                  ':' +
+                  evidenceIndex
+                }
+                className="break-all"
+              >
+                <code>{evidence.filePath}</code>
+                <span> {t('audit.imports')} </span>
+                <code>{evidence.importName}</code>
+              </div>
+            ))}
+      </div>
+    </details>
+  );
+}
+
+interface CycleInspectorProps {
+  readonly inspection: CycleInspection;
+  readonly onClose: () => void;
+}
+
+interface EvidenceEdgeProps {
+  readonly edge: CycleEdgeEvidence;
+  readonly index: number;
+}

package/src/features/audit/adapters/inbound/react/CyclicDependenciesRuleDetails.tsx

@@ -0,0 +1,124 @@
+'use client';
+import React from 'react';
+
+import { SidebarRow } from '@/components/sidebar/SidebarRow';
+import { SidebarSection } from '@/components/sidebar/SidebarSection';
+import { ToggleSwitch } from '@/components/ToggleSwitch';
+import {
+  createCycleInspection,
+  getCycleColor,
+  getCycleId,
+} from '@/features/audit/utils/cycleVisualization';
+import { t } from '@/i18n/i18n';
+import type { PackageCycleDetail } from '@/types/audit';
+import type { CycleInspection, CycleSelection } from '@/types/auditVisualization';
+
+/*** Renders cycle findings with independent highlight switches and toggleable evidence selection. */
+export function CyclicDependenciesRuleDetails({
+  cycles,
+  cycleSelection,
+  inspectedCycleId,
+  onCycleInspectionChange,
+}: CyclicDependenciesRuleDetailsProps) {
+  return (
+    <SidebarSection
+      title={
+        <span className="flex items-center gap-2">
+          <span>{t('audit.rule.cyclicDependencies')}</span>
+          <span className="text-xs font-normal text-neutral-500 dark:text-neutral-400">
+            {cycles.length} {t('audit.cycles')}
+          </span>
+        </span>
+      }
+    >
+      {cycles.map((cycle, index) => (
+        <SidebarRow key={getCycleId(cycle)}>
+          <CycleRow
+            color={getCycleColor(index)}
+            cycle={cycle}
+            index={index}
+            inspected={inspectedCycleId === getCycleId(cycle)}
+            selected={cycleSelection.selectedIds.includes(getCycleId(cycle))}
+            onInspect={() =>
+              onCycleInspectionChange(
+                inspectedCycleId === getCycleId(cycle)
+                  ? null
+                  : createCycleInspection(cycle, index, t('audit.cycle') + ' ' + (index + 1))
+              )
+            }
+            onSelectedChange={selected => {
+              cycleSelection.setSelected(getCycleId(cycle), selected);
+              if (!selected && inspectedCycleId === getCycleId(cycle))
+                onCycleInspectionChange(null);
+            }}
+          />
+        </SidebarRow>
+      ))}
+    </SidebarSection>
+  );
+}
+
+/*** Renders one compact cycle switch; full evidence stays in the graph inspector. */
+function CycleRow({
+  color,
+  cycle,
+  index,
+  inspected,
+  onInspect,
+  onSelectedChange,
+  selected,
+}: CycleRowProps) {
+  const route = cycle.packages.join(' → ');
+  const packageCount = new Set(cycle.packages).size;
+  const label = t('audit.cycle') + ' ' + (index + 1);
+
+  return (
+    <div
+      className="flex items-start gap-2 rounded px-1 py-1"
+      style={selected || inspected ? { backgroundColor: color + '1a' } : undefined}
+    >
+      <button
+        type="button"
+        onClick={onInspect}
+        aria-expanded={inspected}
+        className="min-w-0 flex-1 cursor-pointer rounded text-left focus-visible:outline-2 focus-visible:outline-offset-2"
+        style={inspected ? { boxShadow: `inset 3px 0 ${color}`, paddingLeft: 6 } : undefined}
+        title={route}
+      >
+        <span className="flex items-center gap-1.5 text-xs font-medium">
+          <span>{label}</span>
+          <span className="ml-auto shrink-0 text-[10px] font-normal text-neutral-500 dark:text-neutral-400">
+            {packageCount} pkg
+          </span>
+        </span>
+        <code className="mt-1 block truncate text-[11px] text-neutral-500 dark:text-neutral-400">
+          {route}
+        </code>
+      </button>
+      <ToggleSwitch
+        ariaLabel={label}
+        checkedColor={color}
+        id={'switch-audit-cycle-' + index}
+        onToggle={() => onSelectedChange(!selected)}
+        value={selected}
+      />
+    </div>
+  );
+}
+
+interface CyclicDependenciesRuleDetailsProps {
+  readonly inspectedCycleId?: string | null;
+  readonly cycles: readonly PackageCycleDetail[];
+  readonly cycleSelection: CycleSelection;
+  readonly onCycleInspectionChange: (inspection: CycleInspection | null) => void;
+}
+
+interface CycleRowProps {
+  readonly inspected: boolean;
+  readonly color: string;
+  readonly cycle: PackageCycleDetail;
+  readonly index: number;
+  readonly onInspect: () => void;
+  readonly onSelectedChange: (selected: boolean) => void;
+  readonly selected: boolean;
+}

package/src/features/audit/adapters/inbound/react/useCycleSelection.ts

@@ -0,0 +1,47 @@
+'use client';
+import { isRecord } from '@ankhorage/utility/object';
+import { useLocalStorage } from 'ankh-hooks/store';
+import { useCallback, useMemo } from 'react';
+
+import { resolveSelectedCycleIds } from '@/features/audit/application/use-cases/resolveSelectedCycleIds';
+import { createCycleHighlights } from '@/features/audit/utils/cycleVisualization';
+import { readSettingsEnvironment } from '@/features/settings/utils/readSettingsEnvironment';
+import type { PackageCycleDetail } from '@/types/audit';
+import type { CycleSelection } from '@/types/auditVisualization';
+
+/*** Owns persisted cycle choices independently of sidebar mounting and navigation. */
+export function useCycleSelection(cycles: readonly PackageCycleDetail[]): CycleSelection {
+  const project = process.env.NEXT_PUBLIC_PROJECT_PATH ?? 'default';
+  const [stored, setStored] = useLocalStorage<string>('pkgviz:cycles:v1:' + project, '{}');
+  const choices = useMemo(() => readChoices(stored), [stored]);
+  const enabledByDefault = readSettingsEnvironment().showCycles;
+  const selectedIds = useMemo(
+    () => resolveSelectedCycleIds(cycles, choices, enabledByDefault),
+    [cycles, choices, enabledByDefault]
+  );
+  const highlights = useMemo(
+    () => createCycleHighlights(cycles, selectedIds),
+    [cycles, selectedIds]
+  );
+  const setSelected = useCallback(
+    (id: string, selected: boolean) => {
+      setStored(previous => JSON.stringify({ ...readChoices(previous), [id]: selected }));
+    },
+    [setStored]
+  );
+
+  return useMemo(
+    () => ({ highlights, selectedIds, setSelected }),
+    [highlights, selectedIds, setSelected]
+  );
+}
+
+/*** Parses the versioned persistence payload at the browser boundary. */
+function readChoices(value: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}

package/src/features/audit/application/use-cases/createAuditFromSnapshot.ts

@@ -0,0 +1,28 @@
+import { getPackageCyclesWithMembers } from '@/app/utils/markCyclicPackages';
+import { evaluateAuditRules } from '@/features/audit/domain/evaluateAuditRules';
+import { resolveAuditConfiguration } from '@/features/audit/domain/resolveAuditConfiguration';
+import { getProjectName } from '@/shared/utils/getProjectName';
+import type { Audit, ResolveAuditConfigurationInput } from '@/types/audit';
+import type { ProjectSnapshot } from '@/types/projectAnalysis';
+
+/*** Evaluates audit policy against the same files and weighted graph used by the visualization. */
+export function createAuditFromSnapshot(
+  snapshot: ProjectSnapshot,
+  configurationInput: ResolveAuditConfigurationInput = {}
+): Audit {
+  const configuration = resolveAuditConfiguration(configurationInput);
+  const cyclicPackages = getPackageCyclesWithMembers(snapshot.files, snapshot.graph).cycles;
+  const rules = evaluateAuditRules({ configuration, cyclicPackages });
+
+  return {
+    configuration,
+    evaluation: { cyclicPackages, rules },
+    files: snapshot.files,
+    meta: {
+      language: snapshot.language,
+      projectName: getProjectName(snapshot.projectPath),
+      timeStart: snapshot.timeStart,
+      timeEnd: Date.now(),
+    },
+  };
+}

package/src/features/audit/application/use-cases/resolveSelectedCycleIds.ts

@@ -0,0 +1,18 @@
+import { isRecord } from '@ankhorage/utility/object';
+
+import { getCycleId } from '@/features/audit/utils/cycleVisualization';
+import type { PackageCycleDetail } from '@/types/audit';
+
+/*** Resolves explicit per-cycle choices before the environment default, ignoring invalid storage. */
+export function resolveSelectedCycleIds(
+  cycles: readonly PackageCycleDetail[],
+  stored: unknown,
+  enabledByDefault: boolean
+): readonly string[] {
+  const choices = new Map(isRecord(stored) ? Object.entries(stored) : []);
+  return cycles.flatMap(cycle => {
+    const id = getCycleId(cycle);
+    const choice = choices.get(id);
+    return (typeof choice === 'boolean' ? choice : enabledByDefault) ? [id] : [];
+  });
+}

package/src/features/audit/composition/createAuditAsync.ts

@@ -0,0 +1,11 @@
+import { createAuditFromSnapshot } from '@/features/audit/application/use-cases/createAuditFromSnapshot';
+import { loadProjectSnapshotAsync } from '@/features/project-analysis/composition/loadProjectSnapshotAsync';
+import type { Audit, ResolveAuditConfigurationInput } from '@/types/audit';
+
+/*** Composes a fresh project snapshot and audit evaluation without UI environment state. */
+export async function createAuditAsync(
+  projectPath: string,
+  configurationInput: ResolveAuditConfigurationInput = {}
+): Promise<Audit> {
+  return createAuditFromSnapshot(await loadProjectSnapshotAsync(projectPath), configurationInput);
+}

package/src/features/audit/domain/evaluateAuditRules.ts

@@ -0,0 +1,42 @@
+import type {
+  AuditRuleConfiguration,
+  AuditRuleResult,
+  CyclicDependenciesEvidence,
+  EvaluateAuditRulesInput,
+  PackageCycleDetail,
+} from '@/types/audit';
+
+/*** Evaluates every enabled PKGViz audit rule against one analysis result. */
+export function evaluateAuditRules(input: EvaluateAuditRulesInput): readonly AuditRuleResult[] {
+  const mode = findRuleMode(input.configuration.rules, 'cyclic-dependencies');
+  if (mode === 'off') return [];
+
+  return [evaluateCyclicDependencies(input.cyclicPackages, mode)];
+}
+
+/*** Evaluates cyclic dependencies while applying the configured enforcement mode. */
+function evaluateCyclicDependencies(
+  cycles: readonly PackageCycleDetail[],
+  mode: Exclude<AuditRuleConfiguration['mode'], 'off'>
+): AuditRuleResult<CyclicDependenciesEvidence> {
+  const failed = cycles.length > 0;
+
+  return {
+    id: 'cyclic-dependencies',
+    status: failed ? 'failed' : 'passed',
+    policy: mode === 'block' ? 'blocking' : 'advisory',
+    message: failed
+      ? `Detected ${cycles.length} cyclic package dependenc${cycles.length === 1 ? 'y' : 'ies'}.`
+      : 'No cyclic package dependencies detected.',
+    details: cycles.map(cycle => cycle.packages.join(' → ')),
+    evidence: { cycles },
+  };
+}
+
+/*** Returns the effective mode for one known audit rule. */
+function findRuleMode(
+  rules: readonly AuditRuleConfiguration[],
+  id: AuditRuleConfiguration['id']
+): AuditRuleConfiguration['mode'] {
+  return rules.find(rule => rule.id === id)?.mode ?? 'off';
+}

package/src/features/audit/domain/hasBlockingAuditRuleFailure.ts

@@ -0,0 +1,6 @@
+import type { AuditRuleResult } from '@/types/audit';
+
+/*** Reports whether any blocking audit rule failed. */
+export function hasBlockingAuditRuleFailure(results: readonly AuditRuleResult[]): boolean {
+  return results.some(result => result.policy === 'blocking' && result.status === 'failed');
+}

package/src/features/audit/domain/resolveAuditConfiguration.ts

@@ -0,0 +1,27 @@
+import type {
+  AuditConfiguration,
+  AuditRuleConfiguration,
+  ResolveAuditConfigurationInput,
+} from '@/types/audit';
+
+/*** Resolves explicit audit overrides against the stable default rule policy. */
+export function resolveAuditConfiguration(
+  input: ResolveAuditConfigurationInput = {}
+): AuditConfiguration {
+  let cyclicDependenciesMode: AuditRuleConfiguration['mode'] = 'block';
+
+  for (const rule of input.rules ?? []) {
+    switch (rule.id) {
+      case 'cyclic-dependencies':
+        cyclicDependenciesMode = rule.mode;
+        break;
+      default:
+        throw new Error(`Unknown audit rule "${rule.id}".`);
+    }
+  }
+
+  return {
+    failOnRuleViolation: input.failOnRuleViolation ?? true,
+    rules: [{ id: 'cyclic-dependencies', mode: cyclicDependenciesMode }],
+  };
+}

package/src/features/audit/utils/cycleVisualization.ts

@@ -0,0 +1,86 @@
+import type { PackageCycleDetail } from '@/types/audit';
+import type { CycleFocus, CycleHighlight, CycleInspection } from '@/types/auditVisualization';
+
+const CYCLE_ERROR_COLORS = [
+  '#dc2626',
+  '#7f1d1d',
+  '#fb7185',
+  '#be123c',
+  '#ef4444',
+  '#450a0a',
+  '#f43f5e',
+  '#991b1b',
+] as const;
+
+/*** Returns a stable distinct error-red color for one cycle occurrence. */
+export function getCycleColor(index: number): string {
+  return CYCLE_ERROR_COLORS[index % CYCLE_ERROR_COLORS.length];
+}
+
+/*** Returns the stable UI identity for one cycle occurrence. */
+export function getCycleId(cycle: PackageCycleDetail): string {
+  return JSON.stringify([
+    [...new Set(cycle.packages)].sort(),
+    cycle.edges
+      .map(edge => [edge.from, edge.to])
+      .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+  ]);
+}
+
+/*** Creates one stable cycle highlight descriptor. */
+function createCycleHighlight(cycle: PackageCycleDetail, index: number): CycleHighlight {
+  return {
+    id: getCycleId(cycle),
+    color: getCycleColor(index),
+    cycle,
+  };
+}
+
+/*** Creates graph highlights for the selected cycle occurrence IDs. */
+export function createCycleHighlights(
+  cycles: readonly PackageCycleDetail[],
+  selectedCycleIds: readonly string[]
+): readonly CycleHighlight[] {
+  return cycles.flatMap((cycle, index) => {
+    const id = getCycleId(cycle);
+    return selectedCycleIds.includes(id) ? [createCycleHighlight(cycle, index)] : [];
+  });
+}
+
+/*** Creates the narrowest scope and least depth that expose every active cycle package. */
+export function createCycleFocus(highlights: readonly CycleHighlight[]): CycleFocus | null {
+  const packageNames = [...new Set(highlights.flatMap(highlight => highlight.cycle.packages))];
+  if (packageNames.length === 0) return null;
+
+  const packageSegments = packageNames.map(packageName => packageName.split('.'));
+  const [firstSegments, ...remainingSegments] = packageSegments;
+  const mismatchIndex = firstSegments.findIndex((segment, index) =>
+    remainingSegments.some(segments => segments.at(index) !== segment)
+  );
+  const commonDepth = mismatchIndex === -1 ? firstSegments.length : mismatchIndex;
+  const commonSegments = firstSegments.slice(0, commonDepth);
+  const commonPackage = commonSegments.join('.');
+  const focusSegments = packageNames.includes(commonPackage)
+    ? commonSegments.slice(0, -1)
+    : commonSegments;
+
+  return {
+    currentPackage: focusSegments.join('.'),
+    packageDepth: Math.max(
+      1,
+      ...packageSegments.map(segments => segments.length - focusSegments.length)
+    ),
+  };
+}
+
+/*** Creates the inspector descriptor for one cycle row. */
+export function createCycleInspection(
+  cycle: PackageCycleDetail,
+  index: number,
+  label: string
+): CycleInspection {
+  return {
+    ...createCycleHighlight(cycle, index),
+    label,
+  };
+}

package/src/features/dependency-analysis/adapters/outbound/dependency-graph/analyzeDependencyImportsAsync.ts

@@ -0,0 +1,172 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  createDependencyGraphAsync,
+  type DependencyGraphNodeData,
+  type DependencyImportEvidence,
+} from '@ankhorage/dependency-graph';
+import { resolveFileSystemPathWithinRoot } from '@ankhorage/utility/node/fs';
+
+import type { ImportDefinition } from '@/shared/types';
+import { toPosix } from '@/shared/utils/toPosix';
+
+interface OrderedImport {
+  readonly definition: ImportDefinition;
+  readonly position: number;
+  readonly ordinal: number;
+}
+
+interface AppendEvidenceInput {
+  readonly analysisRoot: string;
+  readonly evidence: DependencyImportEvidence;
+  readonly importNameMode: ImportNameMode;
+  readonly imports: Map<string, OrderedImport[]>;
+  readonly intrinsicMode: ImportIntrinsicMode;
+  readonly ordinal: number;
+  readonly pkg: string;
+  readonly projectRoot: string;
+  readonly sourceTextByFile: Map<string, Promise<string>>;
+}
+
+/*** Returns PKGViz import definitions from the canonical dependency analyzer. */
+export async function analyzeDependencyImportsAsync(
+  projectRoot: string,
+  analysisRoot: string = projectRoot,
+  importNameMode: ImportNameMode = 'package',
+  intrinsicMode: ImportIntrinsicMode = 'canonical'
+): Promise<ReadonlyMap<string, readonly ImportDefinition[]>> {
+  const canonicalProjectRoot = resolveFileSystemPathWithinRoot(projectRoot, '.', {
+    allowRoot: true,
+  });
+  const canonicalAnalysisRoot = resolveFileSystemPathWithinRoot(
+    canonicalProjectRoot,
+    resolveFileSystemPathWithinRoot(analysisRoot, '.', { allowRoot: true }),
+    { allowRoot: true }
+  );
+  const graph = await createDependencyGraphAsync({
+    projects: [{ id: 'current', rootPath: canonicalProjectRoot }],
+  });
+  const nodes = new Map(graph.nodes.map(node => [node.id, node.data] as const));
+  const imports = new Map<string, OrderedImport[]>();
+  const sourceTextByFile = new Map<string, Promise<string>>();
+  let ordinal = 0;
+
+  for (const edge of graph.edges) {
+    const target = nodes.get(edge.target);
+    if (target === undefined) {
+      throw new Error(`Missing dependency-graph target node: ${edge.target}`);
+    }
+
+    const pkg = targetPackage(target);
+    for (const evidence of edge.data.evidence) {
+      if (pkg === '') continue;
+      ordinal = await appendEvidenceAsync({
+        analysisRoot: canonicalAnalysisRoot,
+        evidence,
+        importNameMode,
+        imports,
+        intrinsicMode,
+        ordinal,
+        pkg,
+        projectRoot: canonicalProjectRoot,
+        sourceTextByFile,
+      });
+    }
+  }
+
+  return materializeImports(imports);
+}
+
+type ImportNameMode = 'package' | 'specifier';
+type ImportIntrinsicMode =
+  'canonical' | 'delphi-standard-library' | 'kotlin-standard-library' | 'python-legacy';
+
+/*** Adds one canonical evidence item while retaining the original source declaration position. */
+async function appendEvidenceAsync(input: AppendEvidenceInput): Promise<number> {
+  const absoluteSourceFile = path.resolve(input.projectRoot, input.evidence.sourceFile);
+  const sourceFile = toPosix(path.relative(input.analysisRoot, absoluteSourceFile));
+  const sourceText = await readSourceTextAsync(input.sourceTextByFile, absoluteSourceFile);
+  const current = input.imports.get(sourceFile) ?? [];
+
+  current.push({
+    definition: {
+      name: input.importNameMode === 'specifier' ? input.evidence.specifier : input.pkg,
+      pkg: input.pkg,
+      isIntrinsic: isIntrinsicImport(input.evidence, input.intrinsicMode),
+    },
+    position: sourceText.indexOf(input.evidence.specifier),
+    ordinal: input.ordinal,
+  });
+  input.imports.set(sourceFile, current);
+  return input.ordinal + 1;
+}
+
+/*** Converts collected import evidence into source-order PKGViz definitions. */
+function materializeImports(
+  imports: ReadonlyMap<string, readonly OrderedImport[]>
+): ReadonlyMap<string, readonly ImportDefinition[]> {
+  return new Map(
+    [...imports].map(([sourceFile, entries]) => [
+      sourceFile,
+      [...entries]
+        .sort((left, right) => {
+          const leftPosition = left.position < 0 ? Number.MAX_SAFE_INTEGER : left.position;
+          const rightPosition = right.position < 0 ? Number.MAX_SAFE_INTEGER : right.position;
+          return leftPosition - rightPosition || left.ordinal - right.ordinal;
+        })
+        .map(({ definition }) => definition),
+    ])
+  );
+}
+
+/*** Reads source content once so adapter output preserves source declaration order. */
+function readSourceTextAsync(
+  cache: Map<string, Promise<string>>,
+  sourceFile: string
+): Promise<string> {
+  const cached = cache.get(sourceFile);
+  if (cached !== undefined) return cached;
+
+  const sourceText = readOptionalSourceTextAsync(sourceFile);
+  cache.set(sourceFile, sourceText);
+  return sourceText;
+}
+
+/*** Missing evidence source files retain canonical ordering instead of failing analysis. */
+async function readOptionalSourceTextAsync(sourceFile: string): Promise<string> {
+  try {
+    return await readFile(sourceFile, 'utf8');
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return '';
+    throw error;
+  }
+}
+
+/*** Preserves PKGViz presentation semantics independently from canonical graph classification. */
+function isIntrinsicImport(evidence: DependencyImportEvidence, mode: ImportIntrinsicMode): boolean {
+  if (mode === 'canonical') return evidence.classification === 'intrinsic';
+  if (mode === 'python-legacy') return evidence.specifier.startsWith('.');
+  if (mode === 'delphi-standard-library') {
+    return (
+      evidence.specifier.startsWith('System.') ||
+      evidence.specifier.startsWith('Vcl.') ||
+      evidence.specifier.startsWith('FMX.') ||
+      evidence.specifier.startsWith('Data.') ||
+      evidence.specifier.startsWith('Web.')
+    );
+  }
+
+  return (
+    evidence.specifier.startsWith('kotlin.') ||
+    evidence.specifier.startsWith('java.') ||
+    evidence.specifier.startsWith('javax.')
+  );
+}
+
+/*** Maps canonical dependency-graph node metadata to PKGViz package notation. */
+function targetPackage(target: DependencyGraphNodeData): string {
+  if (target.kind === 'module') return target.path ?? '';
+  if (target.classification === 'intrinsic' && target.focus && target.path === '.') return '';
+  return target.packageName ?? target.label;
+}