mizcausevic-dev/codebase-bloat-tax

Purpose and principal workflow

Codebase Bloat & Technical Debt Tax is a local-first React decision-support app that turns JavaScript manifests, lockfiles, optional build/CI artifacts, and import snippets into a labeled report of dependency, bundle, security, and delivery-cost signals. A developer or engineering lead initiates an analysis in the browser by uploading files, supplying a public GitHub URL, entering an import snippet, choosing a screenshot, or loading the demo. The app builds a dependency graph, optionally enriches it with external lookups, computes estimates and recommendations, validates the report, and presents it for review or export.

Components

Browser application and input

• Browser React entry point — src/main.tsx: mounts the React application into the page root.

• Application coordinator — src/App.tsx: owns the report, busy/error and operator-configuration state; calls the analysis workflow and coordinates report display and export actions.

• Ingestion interface — src/ui/dashboard/IngestView.tsx: offers upload, public-repository, snippet, screenshot/OCR, and demo entry paths and forwards their parsed inputs for analysis.

• Input validation and safety — src/ingestion/validate.ts: enforces filename, size, paste, URL, JSON-depth, and forbidden-key constraints used when accepting untrusted input.

• Input acquisition and parsing — src/ingestion/manifests.ts: provides manifest/file and import-snippet ingestion; README also documents separate screenshot OCR and GitHub Contents ingestion paths.

• Public GitHub ingestion — src/ingestion/github.ts: documented and imported as the public repository manifest fetcher; exact request details are not in the sampled excerpt.

• Screenshot OCR — src/ingestion/screenshots.ts: imported by the ingestion UI to extract package names from images; README says OCR runs in-browser.

Dependency and evidence processing

• Dependency graph resolution — src/graph/resolveNpm.ts: parses npm lockfiles into nodes and dependency edges with a node safety cap; pnpm and Yarn have separate resolver modules in the same graph subsystem.

• Graph normalization and report shaping — src/graph/normalize.ts: imported by the analysis workflow to normalize and serialize dependency graph data for the report.

• Build and CI artifact parsing — src/analysis/artifacts.ts: imported to parse bundler artifacts, Lighthouse data, and CI timestamps as distinct evidence inputs.

• External intelligence lookups — src/intelligence/vulnerabilities.ts: queries OSV for resolved package versions, validates responses, caches results, and reports lookup status; analysis also imports separate npm Registry and Bundlephobia lookups.

Analysis and output

• Analysis orchestration — src/analysis/runAnalysis.ts: parses evidence, optionally runs intelligence lookups, invokes estimate/recommendation models, and assembles the report.

• Decision and estimate models — src/models/bundleImpact.ts: computes bundle-impact estimates, preferring artifact measurements and modeling transfer time from configured network profiles; the analysis workflow also invokes separate mobile, build-wait, opportunity-cost, and alternatives models.

• Report contract — src/schemas/report.ts: defines Zod-validated report structures for estimates, graph data, recommendations, security findings, and lookup status.

• Analysis dashboard — src/ui/dashboard/Dashboard.tsx: report presentation surface, documented by the README as including evidence and recommendations; specific rendering details were not sampled.

• Markdown export — src/export/markdown.ts: creates PR-safe report notes, supports package-name privacy options, and redacts likely secrets, emails, and absolute paths.

• Workflow preview generation — src/export/githubAction.ts: imported by the application to generate a GitHub Action file for preview; it does not automatically commit or write a workflow.

Optional private-repository path

• Private GitHub OAuth function — netlify/functions/github-oauth.ts: exchanges an OAuth code and fetches an allowlisted set of repository files using a read token held in memory for the request.

• Developer / engineering lead — null: external browser user who supplies analysis inputs and reviews or exports the result.

• GitHub Contents API — null: external API used for public repository ingestion and, on a configured server host, private repository reads.

• Lookup providers — null: external npm Registry, Bundlephobia, and OSV services used for optional package metadata, advisory size estimates, and vulnerability findings.

Relationships

• Developer / engineering lead -> Browser React entry point: opens the browser app; README describes a local-first React app and public preview.

• Browser React entry point -> Application coordinator: mounts the React application; the entry module imports and renders it.

• Application coordinator -> Ingestion interface: presents input paths and receives their analysis payloads; the app renders the ingest view and coordinates analysis.

• Ingestion interface -> Input acquisition and parsing: ingests uploaded text and parses import snippets; shown by its imports and handlers.

• Ingestion interface -> Public GitHub ingestion: requests public repository manifests on URL submission; shown by the imported fetcher and handler.

• Ingestion interface -> Screenshot OCR: sends an image for OCR and forwards extracted package names; shown by the screenshot handler.

• Input acquisition and parsing -> Input validation and safety: validates accepted text and filenames; README documents enforced input limits and source imports validation errors.

• Public GitHub ingestion -> GitHub Contents API: fetches manifests from public repositories; the UI identifies the unauthenticated Contents API as the source.

• Application coordinator -> Analysis orchestration: calls analysis with the submitted payload and operator configuration; shown by the analysis call.

• Analysis orchestration -> Dependency graph resolution: resolves dependency data from the supplied lockfile; README documents the ingestion-to-graph pipeline, with npm resolver behavior shown in its source.

• Analysis orchestration -> Build and CI artifact parsing: parses bundler, Lighthouse, and CI evidence before estimate generation; shown by the imported parser calls.

• Analysis orchestration -> External intelligence lookups: conditionally invokes Bundlephobia, npm Registry, and vulnerability lookups when enabled; shown by the parallel lookup calls.

• External intelligence lookups -> Lookup providers: queries OSV for package/version advisories; the vulnerability module calls api.osv.dev. Registry and Bundlephobia calls are documented/imported, but their concrete request details were not sampled.

• Analysis orchestration -> Decision and estimate models: passes artifacts, lookup results, and operator settings into estimate and recommendation calculations; shown by model calls.

• Analysis orchestration -> Report contract: validates the assembled report with the report schema; shown by the schema import and README’s documented Zod contract.

• Analysis orchestration -> Graph normalization and report shaping: converts the normalized graph to report form; shown by graphToReportShape.

• Application coordinator -> Analysis dashboard: supplies the completed report for display; the app owns report state and renders the dashboard.

• Application coordinator -> Markdown export: provides report export actions; the app imports the Markdown export module, though the call site was not included in the excerpt.

• Application coordinator -> Workflow preview generation: generates and displays workflow text from the report’s package-manager information; shown by the workflow handler.

• Developer / engineering lead -> Private GitHub OAuth function: may initiate a private Contents: read flow when hosted and enabled; README documents the server-only path, while the preview disables it.

• Private GitHub OAuth function -> GitHub Contents API: exchanges the OAuth code and requests allowlisted repository files with the resulting bearer token; shown by the function’s fetch calls.

Coverage limits

Several source excerpts are partial, so exact ordering and error handling inside the full analysis and UI are not established. The README documents separate pnpm/Yarn resolvers, lookup caching, and localStorage preference/history behavior, but the sampled sources do not establish their detailed call paths or persistence behavior. The private OAuth function is present, but its client-side invocation is not shown; its use is documented as conditional on server hosting and configuration.