tokentrace 0.21.1 → 0.21.2

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to TokenTrace are documented here.
 
 ## Unreleased
 
+## [0.21.2] - 2026-06-26
+
+### Fixed
+
+- **ProjScan circular-import warnings removed.** Shared scan-health, analytics,
+  evidence, review-queue, project-signal, session-comparison, and unknown-cost
+  repair contracts now live in leaf type modules so the import graph stays
+  acyclic. Added a regression test for these architecture boundaries.
+
+### Changed
+
+- **Low-risk dependency refresh.** Updated patch and minor dependencies within
+  the existing major-version ranges after audit and package-security checks.
+
 ## [0.21.1] - 2026-06-26
 
 ### Changed

package/README.md

@@ -417,7 +417,7 @@ Stop the server with `Ctrl+C` in the terminal where `tokentrace` is running.
 - `npm run security:ioc` scans lockfiles, workflows, and local Claude/VS Code hook files for high-signal supply-chain compromise indicators.
 - Public npm publishing is configured through GitHub Actions Trusted Publishing and provenance from version tags.
 - Socket GitHub checks and ProjScan are used as release guardrails, alongside `npm audit --audit-level=moderate`.
-- `npm run release:check` fails when a gate command exits non-zero. ProjScan warning-level architecture findings, such as circular imports, are reported as release risk and tracked as architecture debt; they do not fail the release unless ProjScan exits non-zero.
+- `npm run release:check` fails when a gate command exits non-zero. The import graph is expected to remain free of circular dependencies; `tests/import-boundaries.test.ts` protects shared type/helper modules from importing higher-level orchestration barrels.
 - Release notes are published directly in GitHub Releases from the relevant changelog section, not as a link-only summary.
 
 See [SECURITY.md](SECURITY.md) for the full security and privacy model.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokentrace",
-  "version": "0.21.1",
+  "version": "0.21.2",
   "mcpName": "io.github.abhiyoheswaran1/tokentrace",
   "description": "Local-first dashboard for AI CLI token, cost, and session analytics.",
   "author": {

package/server.json

@@ -8,12 +8,12 @@
     "url": "https://github.com/abhiyoheswaran1/tokentrace",
     "source": "github"
   },
-  "version": "0.21.1",
+  "version": "0.21.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "tokentrace",
-      "version": "0.21.1",
+      "version": "0.21.2",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/lib/analytics-types.ts

@@ -1,10 +1,7 @@
 import type { DataConfidenceGrade, DataConfidenceScore } from "@/src/lib/data-confidence";
-import type { EvidenceMetric } from "@/src/lib/evidence-trail";
+import type { EvidenceMetric } from "@/src/lib/evidence/metrics";
 import type { LocalRecommendation } from "@/src/lib/recommendations";
-import type { ProjectSignalRow } from "@/src/lib/project-signals";
-import type { ReviewQueueItem } from "@/src/lib/review-queue";
-import type { ScanConfidenceSummary, ScanHealth } from "@/src/lib/scan-health";
-import type { SessionComparisonRow } from "@/src/lib/session-comparison";
+import type { ScanConfidenceSummary, ScanHealth } from "@/src/lib/scan-health-types";
 import type { UsageGuardrailProgress } from "@/src/lib/usage-guardrails";
 
 export type TrendPoint = {
@@ -172,6 +169,60 @@ export type ModelAliasSuggestion = {
   parserHref: string;
 };
 
+export type ReviewQueueCategory =
+  | "guardrail"
+  | "cost-repair"
+  | "session"
+  | "project"
+  | "model"
+  | "cache"
+  | "baseline";
+
+export type ReviewQueueItem = {
+  id: string;
+  severity: "high" | "medium" | "low";
+  category: ReviewQueueCategory;
+  title: string;
+  evidence: string;
+  action: string;
+  href: string;
+  impactLabel: string;
+  impactValue: string;
+};
+
+export type SessionComparisonRow = {
+  sessionId: string;
+  title: string;
+  project: string;
+  tool: string;
+  models: string;
+  totalTokens: number;
+  cost: number | null;
+  peerSessions: number;
+  peerMedianTokens: number;
+  peerMedianCost: number | null;
+  tokenMultiple: number;
+  costMultiple: number | null;
+  severity: "high" | "medium" | "low";
+  flag: "token outlier" | "cost outlier";
+  evidence: string;
+  action: string;
+  href: string;
+};
+
+export type ProjectSignalRow = {
+  id: string;
+  severity: "high" | "medium" | "low";
+  project: string;
+  path: string;
+  signal: "dominant usage" | "unknown cost" | "estimated tokens" | "model concentration";
+  evidence: string;
+  action: string;
+  href: string;
+  metricLabel: string;
+  metricValue: string;
+};
+
 export type DebugScanFile = {
   id: string;
   scanRunId: string;

package/src/lib/evidence/query.ts

@@ -1,5 +1,5 @@
 import { sqlite } from "@/src/db/client";
-import type { AnalyticsFilters } from "@/src/lib/analytics";
+import type { AnalyticsFilters } from "@/src/lib/analytics-types";
 import type { EvidenceMetric } from "@/src/lib/evidence/metrics";
 
 export type EvidenceSessionRow = {

package/src/lib/evidence-trail.ts

@@ -1,4 +1,4 @@
-import type { AnalyticsFilters } from "@/src/lib/analytics";
+import type { AnalyticsFilters } from "@/src/lib/analytics-types";
 import type { EvidenceMetric } from "@/src/lib/evidence/metrics";
 import {
   mapEvidenceTrail,

package/src/lib/project-signals.ts

@@ -1,18 +1,7 @@
-import type { ProjectAnalyticsRow, SessionRow } from "@/src/lib/analytics";
+import type { ProjectAnalyticsRow, ProjectSignalRow, SessionRow } from "@/src/lib/analytics-types";
 import { formatTokens } from "@/src/lib/format";
 
-export type ProjectSignalRow = {
-  id: string;
-  severity: "high" | "medium" | "low";
-  project: string;
-  path: string;
-  signal: "dominant usage" | "unknown cost" | "estimated tokens" | "model concentration";
-  evidence: string;
-  action: string;
-  href: string;
-  metricLabel: string;
-  metricValue: string;
-};
+export type { ProjectSignalRow } from "@/src/lib/analytics-types";
 
 type ProjectSignalInput = {
   totalTokens: number;

package/src/lib/review-queue.ts

@@ -2,33 +2,16 @@ import { formatCurrency, formatTokens } from "@/src/lib/format";
 import type {
   ModelAnalyticsRow,
   ProjectAnalyticsRow,
+  ReviewQueueCategory,
+  ReviewQueueItem,
   SessionRow,
   SummaryMetrics,
   ToolComparisonRow,
   UnknownCostQueueRow
-} from "@/src/lib/analytics";
+} from "@/src/lib/analytics-types";
 import type { UsageGuardrailProgress, UsageGuardrailMetric } from "@/src/lib/usage-guardrails";
 
-export type ReviewQueueCategory =
-  | "guardrail"
-  | "cost-repair"
-  | "session"
-  | "project"
-  | "model"
-  | "cache"
-  | "baseline";
-
-export type ReviewQueueItem = {
-  id: string;
-  severity: "high" | "medium" | "low";
-  category: ReviewQueueCategory;
-  title: string;
-  evidence: string;
-  action: string;
-  href: string;
-  impactLabel: string;
-  impactValue: string;
-};
+export type { ReviewQueueCategory, ReviewQueueItem } from "@/src/lib/analytics-types";
 
 type ReviewQueueInput = {
   summary: Pick<SummaryMetrics, "totalTokens" | "totalCost" | "inputTokens" | "cachedTokens" | "unknownCostInteractions">;

package/src/lib/scan-health-rules.ts

@@ -6,7 +6,7 @@ import type {
   ScanHealthNoteGroup,
   ScanHealthRun,
   SupplyChainHealth
-} from "@/src/lib/scan-health";
+} from "@/src/lib/scan-health-types";
 
 export function incrementCount(target: Record<string, number>, key: string, amount = 1) {
   target[key] = (target[key] ?? 0) + amount;

package/src/lib/scan-health-types.ts

@@ -0,0 +1,104 @@
+export type ScanHealthRun = {
+  id: string;
+  startedAt: number;
+  completedAt: number | null;
+  filesScanned: number;
+  recordsImported: number;
+  warnings: string[];
+  errors: string[];
+};
+
+export type ScanHealthFile = {
+  id: string;
+  scanRunId: string;
+  path: string;
+  modifiedTime: number | null;
+  sizeBytes: number;
+  parser: string | null;
+  status: string;
+  recordsImported: number;
+  warnings: string[];
+  errors: string[];
+  rawMetadata: Record<string, unknown>;
+};
+
+export type ScanConfidenceSummary = {
+  interactions: number;
+  exactTokenInteractions: number;
+  tokenizerEstimateInteractions?: number;
+  simpleEstimateInteractions?: number;
+  highConfidenceTokenInteractions: number;
+  lowConfidenceTokenInteractions: number;
+  unknownTokenInteractions: number;
+  estimatedTokenInteractions: number;
+  exactCostInteractions: number;
+  estimatedCostInteractions: number;
+  unknownCostInteractions: number;
+  unknownCostCauses: {
+    missingModelName: number;
+    missingPricing: number;
+    missingTokenCount: number;
+    other: number;
+  };
+};
+
+export type ScanHealthAction = {
+  label: string;
+  href: string;
+  reason: string;
+  tone: "default" | "warning" | "destructive";
+};
+
+export type SupplyChainHealth = {
+  status: "passed" | "failed" | "not-run";
+  checkedAt: number | null;
+  findings: number;
+  summary: string;
+};
+
+export type ScanHealthNoteGroup = {
+  severity: "warning" | "error";
+  message: string;
+  count: number;
+  examples: string[];
+};
+
+export type ScanHealth = {
+  latestRun: ScanHealthRun | null;
+  lastSuccessfulRun: ScanHealthRun | null;
+  latestFiles: ScanHealthFile[];
+  headline: string;
+  description: string;
+  tone: "success" | "warning" | "destructive" | "secondary";
+  latestStatusCounts: Record<string, number>;
+  parserCounts: Record<string, number>;
+  latestWarnings: string[];
+  latestErrors: string[];
+  latestNoteGroups: ScanHealthNoteGroup[];
+  freshness: {
+    state: "no-scan" | "no-successful-scan" | "fresh" | "stale";
+    lastSuccessfulCompletedAt: number | null;
+    staleAfterMs: number;
+    description: string;
+  };
+  tokenCoverage: {
+    exact: number;
+    tokenizerEstimate: number;
+    simpleEstimate: number;
+    highConfidenceEstimate: number;
+    lowConfidenceEstimate: number;
+    unknown: number;
+    estimated: number;
+    total: number;
+  };
+  costCoverage: {
+    priced: number;
+    exact: number;
+    estimated: number;
+    unknown: number;
+    unknownCauses: ScanConfidenceSummary["unknownCostCauses"];
+    total: number;
+  };
+  supplyChain: SupplyChainHealth;
+  actions: ScanHealthAction[];
+};

package/src/lib/scan-health.ts

@@ -8,111 +8,23 @@ import {
   uniqueMessages,
   type ScanHealthRuleStats
 } from "@/src/lib/scan-health-rules";
+import type {
+  ScanConfidenceSummary,
+  ScanHealth,
+  ScanHealthFile,
+  ScanHealthRun,
+  SupplyChainHealth
+} from "@/src/lib/scan-health-types";
 
-export type ScanHealthRun = {
-  id: string;
-  startedAt: number;
-  completedAt: number | null;
-  filesScanned: number;
-  recordsImported: number;
-  warnings: string[];
-  errors: string[];
-};
-
-export type ScanHealthFile = {
-  id: string;
-  scanRunId: string;
-  path: string;
-  modifiedTime: number | null;
-  sizeBytes: number;
-  parser: string | null;
-  status: string;
-  recordsImported: number;
-  warnings: string[];
-  errors: string[];
-  rawMetadata: Record<string, unknown>;
-};
-
-export type ScanConfidenceSummary = {
-  interactions: number;
-  exactTokenInteractions: number;
-  tokenizerEstimateInteractions?: number;
-  simpleEstimateInteractions?: number;
-  highConfidenceTokenInteractions: number;
-  lowConfidenceTokenInteractions: number;
-  unknownTokenInteractions: number;
-  estimatedTokenInteractions: number;
-  exactCostInteractions: number;
-  estimatedCostInteractions: number;
-  unknownCostInteractions: number;
-  unknownCostCauses: {
-    missingModelName: number;
-    missingPricing: number;
-    missingTokenCount: number;
-    other: number;
-  };
-};
-
-export type ScanHealthAction = {
-  label: string;
-  href: string;
-  reason: string;
-  tone: "default" | "warning" | "destructive";
-};
-
-export type SupplyChainHealth = {
-  status: "passed" | "failed" | "not-run";
-  checkedAt: number | null;
-  findings: number;
-  summary: string;
-};
-
-export type ScanHealthNoteGroup = {
-  severity: "warning" | "error";
-  message: string;
-  count: number;
-  examples: string[];
-};
-
-export type ScanHealth = {
-  latestRun: ScanHealthRun | null;
-  lastSuccessfulRun: ScanHealthRun | null;
-  latestFiles: ScanHealthFile[];
-  headline: string;
-  description: string;
-  tone: "success" | "warning" | "destructive" | "secondary";
-  latestStatusCounts: Record<string, number>;
-  parserCounts: Record<string, number>;
-  latestWarnings: string[];
-  latestErrors: string[];
-  latestNoteGroups: ScanHealthNoteGroup[];
-  freshness: {
-    state: "no-scan" | "no-successful-scan" | "fresh" | "stale";
-    lastSuccessfulCompletedAt: number | null;
-    staleAfterMs: number;
-    description: string;
-  };
-  tokenCoverage: {
-    exact: number;
-    tokenizerEstimate: number;
-    simpleEstimate: number;
-    highConfidenceEstimate: number;
-    lowConfidenceEstimate: number;
-    unknown: number;
-    estimated: number;
-    total: number;
-  };
-  costCoverage: {
-    priced: number;
-    exact: number;
-    estimated: number;
-    unknown: number;
-    unknownCauses: ScanConfidenceSummary["unknownCostCauses"];
-    total: number;
-  };
-  supplyChain: SupplyChainHealth;
-  actions: ScanHealthAction[];
-};
+export type {
+  ScanConfidenceSummary,
+  ScanHealth,
+  ScanHealthAction,
+  ScanHealthFile,
+  ScanHealthNoteGroup,
+  ScanHealthRun,
+  SupplyChainHealth
+} from "@/src/lib/scan-health-types";
 
 export function buildScanHealth({
   scanRuns,

package/src/lib/session-comparison.ts

@@ -1,25 +1,7 @@
-import type { SessionRow } from "@/src/lib/analytics";
+import type { SessionComparisonRow, SessionRow } from "@/src/lib/analytics-types";
 import { formatCurrency, formatTokens } from "@/src/lib/format";
 
-export type SessionComparisonRow = {
-  sessionId: string;
-  title: string;
-  project: string;
-  tool: string;
-  models: string;
-  totalTokens: number;
-  cost: number | null;
-  peerSessions: number;
-  peerMedianTokens: number;
-  peerMedianCost: number | null;
-  tokenMultiple: number;
-  costMultiple: number | null;
-  severity: "high" | "medium" | "low";
-  flag: "token outlier" | "cost outlier";
-  evidence: string;
-  action: string;
-  href: string;
-};
+export type { SessionComparisonRow } from "@/src/lib/analytics-types";
 
 function median(values: number[]) {
   if (!values.length) return 0;

package/src/lib/unknown-cost-repair/auto-classify.ts

@@ -1,46 +1,21 @@
 import { prepareCached } from "@/src/db/prepared";
 import { modelNameCandidates } from "@/src/lib/model-aliases";
-import type { UnknownCostRepairWorkbenchGroup } from "@/src/lib/unknown-cost-repair/types";
-
-export type AutoClassificationRule = "exact-model" | "family-fragment" | "parser-source" | "none";
-
-export type AutoClassification = {
-  suggestedModel: string | null;
-  suggestedProvider: string | null;
-  confidence: number;
-  rule: AutoClassificationRule;
-  evidence: {
-    matchedRows: number;
-    sampleSourceFile: string | null;
-  };
-};
-
-export type ClassifyInput = {
-  cause: UnknownCostRepairWorkbenchGroup["cause"];
-  providerId: string;
-  model: string;
-  sourceFile: string;
-};
-
-export type PricedModelRow = {
-  providerId: string;
-  providerName: string;
-  modelName: string;
-  usageCount: number;
-};
-
-export type SourcePricedRow = {
-  sourceFile: string;
-  providerId: string;
-  providerName: string;
-  modelName: string;
-  usageCount: number;
-};
-
-export type ClassificationLookups = {
-  pricedByProvider: Map<string, PricedModelRow[]>;
-  pricedBySource: Map<string, SourcePricedRow>;
-};
+import type {
+  AutoClassification,
+  ClassificationLookups,
+  ClassifyInput,
+  PricedModelRow,
+  SourcePricedRow
+} from "@/src/lib/unknown-cost-repair/classification-types";
+
+export type {
+  AutoClassification,
+  AutoClassificationRule,
+  ClassificationLookups,
+  ClassifyInput,
+  PricedModelRow,
+  SourcePricedRow
+} from "@/src/lib/unknown-cost-repair/classification-types";
 
 export function buildClassificationLookups(): ClassificationLookups {
   const pricedRows = prepareCached(

package/src/lib/unknown-cost-repair/classification-types.ts

@@ -0,0 +1,41 @@
+import type { UnknownCostRepairCause } from "@/src/lib/repair-actions";
+
+export type AutoClassificationRule = "exact-model" | "family-fragment" | "parser-source" | "none";
+
+export type AutoClassification = {
+  suggestedModel: string | null;
+  suggestedProvider: string | null;
+  confidence: number;
+  rule: AutoClassificationRule;
+  evidence: {
+    matchedRows: number;
+    sampleSourceFile: string | null;
+  };
+};
+
+export type ClassifyInput = {
+  cause: UnknownCostRepairCause;
+  providerId: string;
+  model: string;
+  sourceFile: string;
+};
+
+export type PricedModelRow = {
+  providerId: string;
+  providerName: string;
+  modelName: string;
+  usageCount: number;
+};
+
+export type SourcePricedRow = {
+  sourceFile: string;
+  providerId: string;
+  providerName: string;
+  modelName: string;
+  usageCount: number;
+};
+
+export type ClassificationLookups = {
+  pricedByProvider: Map<string, PricedModelRow[]>;
+  pricedBySource: Map<string, SourcePricedRow>;
+};

package/src/lib/unknown-cost-repair/types.ts

@@ -1,4 +1,4 @@
-import type { AutoClassification } from "@/src/lib/unknown-cost-repair/auto-classify";
+import type { AutoClassification } from "@/src/lib/unknown-cost-repair/classification-types";
 import type { UnknownCostRepairAction, UnknownCostRepairCause } from "@/src/lib/repair-actions";
 
 export type UnknownCostRepairStatus = "unresolved" | "ignored" | "resolved" | "needs-parser-review";