Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

First-Party Source Resolution

All first-party monorepo development and validation flows must resolve local @lapis-notes/* package imports from source under each dependency’s src/ tree. Resolving those imports through package dist/ outputs during development is forbidden.

Rule

  • Apply this rule to every Vite-driven local flow in the repo, including app hosts, package-local vite dev sessions, Vitest or Vite-powered validation, and any other development-time module graph evaluation.
  • Apply the same source-first expectation to package-local TypeScript and Svelte diagnostics. Checks that do not load Vite must provide equivalent tsconfig path mappings for any first-party self-imports they validate.
  • Apply the same source-first expectation to other repo-local check tools that compile or typecheck first-party imports, including TypeDoc and package-local custom tsconfig files such as typedoc.tsconfig.json or tsconfig.check.json.
  • Resolve both root imports such as @lapis-notes/search and subpath imports such as @lapis-notes/api/icon or @lapis-notes/ui/button to source.
  • Apply the same rule to first-party stylesheet imports. CSS or SCSS @import specifiers such as @lapis-notes/ui/theme.css or plugin app.css entries must resolve into dependency src/ trees during local development instead of packaged dist/ CSS artifacts.
  • Apply the same rule to self-imports. A package importing its own published name during development must still resolve back into its own src/ tree instead of its packaged dist/ exports.
  • Do not add or preserve package-specific dist/ fallbacks in dev because a source file currently fails to compile. Fix the underlying source or tooling issue instead.
  • tsconfig.pack.json is for svelte-package prepack only. Do not point validation, TypeDoc, or other check tools at pack tsconfigs; those configs intentionally omit cross-package source paths.
  • Published package manifests may continue to export dist/ artifacts for packaging and external consumption, but repo-local development resolution must override those exports back to source.

Enforcement

  • The repo-root pnpm check:source-resolution command is the executable enforcement point for this contract.
  • That guard loads each package’s Vite config in development mode, resolves real first-party @lapis-notes/* imports from package source files and stylesheet @import sources, and fails if any resolution lands outside the dependency’s src/ tree.
  • The same guard resolves explicit subpath entrypoints (for example @lapis-notes/ui/table-dnd/sensors) through workspace, desktop-electron, and web app-host Vite configs using real cross-package importers, because those hosts keep separate dev resolver registries from package-local Vite configs.
  • The same command runs scripts/check-first-party-tsconfig-resolution.mjs, which resolves real first-party imports through each package’s Svelte/TypeScript tsconfig paths mappings without relying on packaged dist/ outputs. It also auto-discovers package.json export subpaths that wildcard paths patterns cannot reach and requires them to stay listed in firstPartySourceExplicitSubpathEntrypoints.
  • The same command runs scripts/check-first-party-vitest-resolution.mjs, which loads each package’s vitest.config or vite.config in test mode and resolves first-party imports from Vitest test files (including vi.mock("@lapis-notes/...") targets) to dependency src/ trees instead of packaged dist/ outputs.
  • The same command runs scripts/sync-first-party-source-tsconfig-paths.mjs --check so package tsconfig.json and tsconfig.app.json files keep first-party paths mappings in sync with the Vite source-resolution registry for Svelte and TypeScript diagnostics. When that sync script writes updates, it also runs Prettier on the touched tsconfig files so package check:format stays aligned without a separate manual pnpm fmt pass.
  • The same command validates plugin vite.styles.config.ts build configs that @reference workspace app.css can still resolve shared UI CSS entrypoints from source (for example @lapis-notes/ui/theme.css imported by the workspace stylesheet).
  • The same command rejects tsconfig.pack.json references outside prepack/build scripts so check and docs tooling cannot accidentally depend on packaged dist/ outputs.
  • Agents and contributors must treat failures from that guard as contract violations, not optional warnings.