From 5de2390edcc87fa1d33dbac77743ef9cf8806b72 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 2 Nov 2025 18:24:14 +0000 Subject: [PATCH 1/4] Initial plan From b9abc22736a50d4f5d985ba3bd71d4778623a2ee Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 2 Nov 2025 18:33:44 +0000 Subject: [PATCH 2/4] Add comprehensive Copilot development guide Co-authored-by: saberzero1 <8161064+saberzero1@users.noreply.github.com> --- .github/copilot-instructions.md | 391 +++++ package-lock.json | 2348 +++++++++++++++---------------- 2 files changed, 1512 insertions(+), 1227 deletions(-) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..72377e4 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,391 @@ +# Quartz Syncer - Copilot Development Guide + +## Project Overview + +Quartz Syncer is an Obsidian plugin for managing and publishing notes to Quartz, a fast static-site generator. This is a TypeScript/Svelte project that compiles to a single JavaScript bundle (`main.js`) for use as an Obsidian plugin. + +**Repository Size**: ~250MB (mostly node_modules) +**Main Entry Point**: `main.ts` (534 lines) +**Languages**: TypeScript, Svelte, JavaScript +**Build Tool**: esbuild +**Package Manager**: npm +**Node Version**: 20.6.0 (specified in `.nvmrc`) + +## Build and Development Commands + +### Critical: Command Execution Order + +**ALWAYS run `npm install` first** before any other command after cloning or when dependencies change. Build, lint, and test commands will fail without dependencies installed. + +### Standard Commands (Run in Order) + +1. **Install dependencies** (REQUIRED FIRST): + ```bash + npm install + ``` + - Takes ~45-50 seconds + - Installs git hooks via husky (runs automatically via prepare script) + - May show deprecation warnings (safe to ignore) + - May show 3 moderate security vulnerabilities in svelte dependencies (known issue, doesn't affect build) + +2. **Development build** (with sourcemaps): + ```bash + npm run dev + ``` + - Creates `main.js` with inline sourcemaps (~3.3MB) + - Takes ~800-900ms + - Runs post-build script `generateSyncerSettings.mjs` automatically + - Also copies files to `./docs/.obsidian/plugins/quartz-syncer/` for testing + +3. **Production build**: + ```bash + npm run build + ``` + - Creates optimized `main.js` (~1.0MB, no sourcemaps) + - Takes ~800ms + - **THIS IS THE COMMAND CI USES** - always validate with this before committing + +4. **Run tests**: + ```bash + npm run test + ``` + - Uses Jest with ts-jest preset + - Takes ~5-6 seconds + - Currently 2 test suites, 7 tests (all passing) + - Test files: `src/utils/utils.test.ts`, `src/publisher/Publisher.test.ts` + +5. **Lint code**: + ```bash + npm run lint + ``` + - Uses ESLint with TypeScript and Svelte support + - Checks `.ts` and `.svelte` files + - Takes ~2-3 seconds when passing + - **Run before committing** - CI will fail if linting fails + +6. **Check formatting**: + ```bash + npm run check-formatting + ``` + - Uses Prettier to check formatting + - Takes ~1-2 seconds + - **Run before committing** - CI will fail if formatting is wrong + +7. **Auto-fix formatting**: + ```bash + npm run format + ``` + - Auto-formats all files with Prettier + - Takes ~2-3 seconds + - Run this if `check-formatting` fails + +8. **Type checking**: + ```bash + npm run typecheck + ``` + - Runs TypeScript compiler in check mode (no emit) + - Takes ~2-3 seconds + - **Run before committing** - CI will fail if types are wrong + +### Complete Validation Sequence + +Before committing changes, run these commands in order (this matches CI): +```bash +npm install +npm run lint +npm run check-formatting +npm run typecheck +npm run build +npm run test +``` + +Shortcut using justfile (if `just` is installed): +```bash +just check # Runs lint, test, check-formatting, typecheck +just full # Runs lint, check, and prod build +``` + +## Continuous Integration (GitHub Actions) + +### CI Workflows Overview + +CI runs on **every PR and push to main/master**. The following jobs run in parallel: + +1. **lint-and-check-formatting**: ESLint + Prettier checks +2. **build**: Production build (uploads `main.js` artifact) +3. **run-tests**: Jest tests +4. **run-typecheck**: TypeScript type checking + +**All four jobs must pass** for CI to succeed. Each job: +- Uses Node version from `.nvmrc` (20.6.0) +- Runs `npm install` first +- Uses npm cache for faster builds + +### Additional Workflows + +- **CodeQL Advanced**: Security scanning (runs on push to main/backup, PRs, and weekly schedule) +- **Release**: Creates GitHub releases when tags are pushed (runs `npm ci --include=dev` then `npm run build`) + +### Common CI Failures + +- **Linting failures**: Run `npm run lint-fix` then `npm run format` to auto-fix most issues +- **Type errors**: Fix TypeScript errors shown by `npm run typecheck` +- **Test failures**: Fix tests shown by `npm run test` +- **Formatting failures**: Run `npm run format` to auto-fix + +## Project Structure + +### Root Files +- `main.ts` - Plugin entry point (534 lines, defines DEFAULT_SETTINGS, main plugin class) +- `manifest.json` - Obsidian plugin manifest (version, metadata) +- `package.json` - npm dependencies and scripts +- `tsconfig.json` - TypeScript configuration (extends @tsconfig/svelte) +- `jest.config.js` - Jest test configuration +- `eslint.config.mjs` - ESLint configuration (flat config format) +- `esbuild.config.mjs` - Build configuration +- `.prettierrc.json` - Prettier formatting rules (tabs, 80 chars, semicolons) +- `.editorconfig` - Editor settings (tabs, UTF-8) +- `.nvmrc` - Node version (20.6.0) +- `justfile` - Just task runner recipes (optional, not required) +- `version-bump.mjs` - Script to update version in manifest.json, versions.json, package.json +- `styles.css` - Plugin styles (11KB) + +### Source Code Structure (`src/`) + +``` +src/ +├── compiler/ # Frontmatter and plugin compilation +│ ├── FrontmatterCompiler.ts +│ ├── PluginCompiler.ts +│ ├── SyncerPageCompiler.ts +│ └── plugins/ # Dataview, Excalidraw, Mermaid compilers +├── models/ # Data models and settings +│ ├── settings.ts # Plugin settings interface +│ ├── ProgressBar.ts +│ ├── SyncerTab.ts +│ └── TreeNode.ts +├── publishFile/ # File publishing logic +│ ├── PublishFile.ts +│ ├── Validator.ts +│ ├── DataStore.ts +│ ├── FileMetaDataManager.ts +│ └── ObsidianFrontMatterEngine.ts +├── publisher/ # Publishing workflow +│ ├── Publisher.ts +│ ├── PublishStatusManager.ts +│ └── Publisher.test.ts # Tests +├── repositoryConnection/ # GitHub API integration +│ ├── RepositoryConnection.ts +│ └── QuartzSyncerSiteManager.ts +├── ui/ # UI components (Svelte) +│ ├── Icon.svelte +│ ├── LineDiff.svelte +│ ├── TreeView/ # TreeNode.svelte, TreeView.svelte +│ └── suggest/ # Auto-suggest components +├── utils/ # Utility functions +│ ├── utils.ts +│ ├── utils.test.ts # Tests +│ ├── regexes.ts +│ └── styles.ts +└── views/ # Settings and UI views + ├── QuartzSyncerSettingTab.ts + ├── PublicationCenter/ # DiffView.svelte, PublicationCenter.svelte + └── SettingsView/ # Settings UI components +``` + +### Other Directories + +- `docs/` - Documentation markdown files (Obsidian vault for plugin documentation) +- `content/` - Test content (gitignored except .obsidian config) +- `scripts/` - Build scripts (`generateSyncerSettings.mjs`) +- `__mocks__/` - Jest mocks + +## Configuration Files Deep Dive + +### ESLint (`eslint.config.mjs`) +- Uses flat config format (new ESLint style) +- **Ignores**: `**/*.js`, build outputs, scripts, test vaults, content, docs +- **Plugins**: TypeScript, Svelte, TSDoc, Prettier +- **Key Rules**: + - `prettier/prettier: error` - Prettier violations are errors + - `@typescript-eslint/no-explicit-any: error` - No `any` type allowed + - `no-unused-vars` with ignore pattern `^_` for unused params + - Custom padding rules for blank lines before returns/ifs/functions + - Svelte files must use `script lang="ts"` + +### Prettier (`.prettierrc.json`) +- **Print width**: 80 characters +- **Indentation**: Tabs (not spaces) +- **Semicolons**: Required +- **Quotes**: Double quotes +- **Plugin**: prettier-plugin-svelte + +### TypeScript (`tsconfig.json`) +- Extends `@tsconfig/svelte/tsconfig.json` +- **Target**: es2024 +- **Module**: commonjs +- **Strict**: `noImplicitAny: true` +- **Includes**: All `.ts`, `.js`, `.svelte` files, config files + +### Build (`esbuild.config.mjs`) +- **Entry**: `main.ts` +- **Output**: `main.js` (CommonJS format) +- **External**: obsidian, electron, built-in Node modules +- **Target**: es2024 +- **Sourcemap**: Inline for dev, false for production +- **Plugins**: esbuild-svelte with svelte-preprocess +- Svelte CSS is injected into bundle + +## Dependencies + +### Runtime Dependencies +- `obsidian` - Obsidian API (dev dependency, provided by Obsidian) +- `@octokit/core` - GitHub REST API client +- `obsidian-dataview`, `@blacksmithgu/datacore` - Dataview integration +- `axios` - HTTP client +- `luxon` - Date/time handling +- `diff` - Text diffing +- `crypto-js`, `js-base64`, `lz-string` - Encoding/encryption utilities +- `svelte` - UI framework (dev dependency, compiled into bundle) + +### Development Tools +- TypeScript 5.2.2 +- ESLint 9.28.0 with TypeScript and Svelte plugins +- Prettier 3.0.3 +- Jest 29.7.0 with ts-jest +- esbuild 0.25.5 +- Husky 8.0.3 (git hooks) +- lint-staged 16.1.0 (pre-commit formatting) + +## Common Development Patterns + +### Making Code Changes + +1. **Before starting**: Ensure clean build state + ```bash + npm install + npm run build + npm run test + ``` + +2. **During development**: Use dev build for faster iteration + ```bash + npm run dev + ``` + +3. **Before committing**: Run full validation + ```bash + npm run format # Auto-fix formatting + npm run lint # Check code quality + npm run typecheck # Check types + npm run build # Production build + npm run test # Run tests + ``` + +### Adding New Dependencies + +1. Install the dependency: + ```bash + npm install + ``` + +2. For dev dependencies: + ```bash + npm install --save-dev + ``` + +3. If adding external runtime deps, add to `external` array in `esbuild.config.mjs` if they should not be bundled (e.g., Obsidian API) + +### Adding Tests + +- Test files use `.test.ts` suffix (e.g., `utils.test.ts`) +- Place tests next to the code they test +- Use Jest with ts-jest preset +- Mock Obsidian API as needed (see `__mocks__/` directory) +- Run specific test: `npx jest ` + +### Svelte Components + +- Use `.svelte` extension +- Must have `