Merge pull request #80 from coldenate/agent/refactor-folder-structure-and-improve-types

coldenate · web-flow · commit 7fa20e134cae · 2025-07-23T13:26:10.000-05:00
Scaffold modular refactor structure
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -0,0 +1,17 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": "./tsconfig.json"
+  },
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:@typescript-eslint/recommended-requiring-type-checking"
+  ],
+  "env": {
+    "node": true,
+    "es2020": true
+  }
+}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,20 @@
+name: CI
+on:
+    push:
+        branches: [main]
+    pull_request:
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v3
+            - uses: actions/setup-node@v3
+              with:
+                  node-version: 18
+            - run: npm ci
+            - run: npm run lint
+            - run: npm run format
+            - run: npm run typecheck
+            - run: npm test -- --runInBand
+            - run: npm run deps
diff --git a/.gitignore b/.gitignore
@@ -7,3 +7,5 @@ dist-ssr
 exampleCollections.json
 exampleItems.json
 exampleUnfileditems.json
+
+docs/deps.svg
diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx lint-staged
diff --git a/.nvmrc b/.nvmrc
@@ -1 +1 @@
-16.15.1
+18
diff --git a/__mocks__/remnoteAdapter.ts b/__mocks__/remnoteAdapter.ts
@@ -0,0 +1,5 @@
+export const createRem = jest.fn(
+	async (_plugin: unknown, title: string, parentId?: string) => `mock-${title}`
+);
+export const moveRem = jest.fn(async () => {});
+export const deleteRem = jest.fn(async () => {});
diff --git a/jest.config.cjs b/jest.config.cjs
@@ -0,0 +1,5 @@
+module.exports = {
+	preset: 'ts-jest',
+	testEnvironment: 'node',
+	testMatch: ['**/__tests__/**/*.test.ts'],
+};
diff --git a/jest.config.js b/jest.config.js
diff --git a/lint-staged.config.js b/lint-staged.config.js
@@ -0,0 +1,4 @@
+module.exports = {
+  '**/*.{ts,tsx}': ['eslint --fix', 'prettier --write'],
+  '**/*.{json,md,css}': ['prettier --write']
+};
diff --git a/package.json b/package.json
@@ -5,12 +5,19 @@
 	"license": "MIT",
 	"scripts": {
 		"check-types": "tsc",
+		"typecheck": "tsc --noEmit",
+		"lint": "eslint . --ext .ts,.tsx",
+		"format": "prettier --check .",
+		"prepare": "husky install",
 		"start:dev": "cross-env NODE_ENV=development webpack-dev-server --color --progress --no-open",
 		"dev": "concurrently \"npm run start:dev\" \"npm run test:watch\"",
+		"devSync": "ts-node src/devSyncCli.ts",
 		"test": "jest",
 		"test:watch": "jest --watch",
 		"build": "npx remnote-plugin validate && shx rm -rf dist && cross-env NODE_ENV=production webpack --color --progress && shx cp README.md dist && cd dist && bestzip ../PluginZip.zip ./*",
-		"generate-snippet": "ts-node scripts/generateCssSnippet.ts"
+		"generate-snippet": "ts-node scripts/generateCssSnippet.ts",
+		"docs": "typedoc",
+		"deps": "madge --image docs/deps.svg src/modules"
 	},
 	"dependencies": {
 		"@remnote/plugin-sdk": "0.0.44",
@@ -25,20 +32,26 @@
 		"@types/node": "^18.0.3",
 		"@types/react": "^17.0.2",
 		"@types/react-dom": "^17.0.2",
+		"@typescript-eslint/eslint-plugin": "^6.7.0",
+		"@typescript-eslint/parser": "^6.7.0",
 		"autoprefixer": "^10.4.7",
 		"bestzip": "^2.2.1",
 		"concurrently": "^7.2.2",
 		"copy-webpack-plugin": "^11.0.0",
 		"cross-env": "^7.0.3",
 		"css-loader": "^6.7.1",
 		"esbuild-loader": "^4.3.0",
+		"eslint": "^8.50.0",
 		"html-webpack-plugin": "^5.5.0",
+		"husky": "^8.0.0",
 		"jest": "^29.7.0",
+		"lint-staged": "^15.0.0",
 		"mini-css-extract-plugin": "^2.6.1",
 		"patch-package": "^8.0.0",
 		"postcss": "^8.4.31",
 		"postcss-import": "^14.1.0",
 		"postcss-loader": "^7.0.0",
+		"prettier": "^2.8.8",
 		"react-refresh": "^0.14.0",
 		"shx": "^0.3.4",
 		"style-loader": "^3.3.1",
@@ -48,6 +61,11 @@
 		"typescript": "^4.7.4",
 		"webpack": "^5.73.0",
 		"webpack-cli": "^4.10.0",
-		"webpack-dev-server": "^4.15.1"
+		"webpack-dev-server": "^4.15.1",
+		"typedoc": "^0.25.5",
+		"madge": "^6.0.0"
+	},
+	"engines": {
+		"node": "^18"
 	}
 }
diff --git a/prettier.config.cjs b/prettier.config.cjs
@@ -0,0 +1,5 @@
+module.exports = {
+	semi: true,
+	singleQuote: true,
+	trailingComma: 'all',
+};
diff --git a/src/devSyncCli.ts b/src/devSyncCli.ts
@@ -0,0 +1,28 @@
+import { buildSyncTree } from './modules/tree/buildSyncTree';
+import { diffTrees } from './modules/diff/diffTrees';
+import { applyOps } from './modules/executor/applyOps';
+import { loadSnapshot, saveSnapshot } from './modules/storage/snapshotRepository';
+import { log } from './modules/logging';
+import fs from 'fs';
+
+async function main() {
+	const [, , fixture, flag] = process.argv;
+	if (!fixture) {
+		console.error('Usage: devSync <fixture> [--dry-run]');
+		process.exit(1);
+	}
+	const data = JSON.parse(fs.readFileSync(fixture, 'utf8'));
+	const tree = buildSyncTree(data);
+	const snapshot = await loadSnapshot();
+  const ops = diffTrees(snapshot as any, tree);
+  if (flag === '--dry-run') {
+    log('info', 'Planned ops', ops);
+  } else {
+    await applyOps(ops);
+    await saveSnapshot(tree as any);
+  }
+}
+
+main().catch((err) => {
+	console.error(err);
+});
diff --git a/src/modules/api/remnoteAdapter.ts b/src/modules/api/remnoteAdapter.ts
@@ -0,0 +1,18 @@
+// RemNote SDK adapter
+// TODO: extract existing SDK calls into this module
+export async function createRem(
+	plugin: unknown,
+	title: string,
+	parentId?: string
+): Promise<string> {
+	// Placeholder implementation for tests
+	return `rem-${title}`;
+}
+
+export async function moveRem(plugin: unknown, id: string, newParentId: string): Promise<void> {
+	// Placeholder implementation
+}
+
+export async function deleteRem(plugin: unknown, id: string): Promise<void> {
+	// Placeholder implementation
+}
diff --git a/src/modules/api/zoteroClient.ts b/src/modules/api/zoteroClient.ts
@@ -0,0 +1,17 @@
+// Zotero HTTP client
+// TODO: move all network code here
+export async function fetchLibrary(): Promise<any> {
+	// TODO fetch data from Zotero
+	return {};
+}
+
+export function normalizeZoteroItem(raw: any): import('../models/interfaces').SyncNode {
+	return {
+		key: raw.key,
+		type: raw.itemType,
+		title: raw.title ?? '',
+		parentKey: raw.parentKey,
+		children: [],
+		raw,
+	} as any;
+}
diff --git a/src/modules/diff/__tests__/diffTrees.test.ts b/src/modules/diff/__tests__/diffTrees.test.ts
@@ -0,0 +1,9 @@
+import { diffTrees } from '../diffTrees';
+import { buildSyncTree } from '../../tree/buildSyncTree';
+
+test.skip('diffTrees returns empty list for identical trees', () => {
+	// TODO implement
+	const a = buildSyncTree({});
+	const b = buildSyncTree({});
+	expect(diffTrees(a, b)).toEqual([]);
+});
diff --git a/src/modules/diff/diffTrees.ts b/src/modules/diff/diffTrees.ts
@@ -0,0 +1,6 @@
+import { SyncTree } from '../models/interfaces';
+
+export function diffTrees(base: SyncTree, target: SyncTree) {
+  // TODO: implement diff algorithm
+  return [];
+}
diff --git a/src/modules/errors/index.ts b/src/modules/errors/index.ts
@@ -0,0 +1,4 @@
+export class SyncError extends Error {}
+export class FetchError extends SyncError {}
+export class DiffError extends SyncError {}
+export class ApplyError extends SyncError {}
diff --git a/src/modules/executor/__tests__/applyOps.test.ts b/src/modules/executor/__tests__/applyOps.test.ts
@@ -0,0 +1,6 @@
+import { applyOps } from '../applyOps';
+
+test.skip('applyOps handles empty ops', async () => {
+	// TODO implement
+	await applyOps([]);
+});
diff --git a/src/modules/executor/applyOps.ts b/src/modules/executor/applyOps.ts
@@ -0,0 +1,8 @@
+import { SyncOp } from '../models/interfaces';
+
+export async function applyOps(ops: SyncOp[]) {
+  // TODO: extract RemNote mutations here
+  for (const op of ops) {
+    // no-op
+  }
+}
diff --git a/src/modules/hydration/hydrateProperties.ts b/src/modules/hydration/hydrateProperties.ts
@@ -0,0 +1,4 @@
+// TODO: move property hydration helpers here
+export function hydrateProperties() {
+  // placeholder
+}
diff --git a/src/modules/logging/index.ts b/src/modules/logging/index.ts
@@ -0,0 +1,11 @@
+type Level = 'debug' | 'info' | 'warn' | 'error';
+
+export function log(level: Level, ...args: unknown[]) {
+	const env = process.env.LOG_LEVEL ?? 'info';
+	const levels: Level[] = ['debug', 'info', 'warn', 'error'];
+	if (levels.indexOf(level) >= levels.indexOf(env as Level)) {
+		const method = level === 'debug' ? 'log' : level;
+		// eslint-disable-next-line no-console
+		(console as any)[method](...args);
+	}
+}
diff --git a/src/modules/models/interfaces.ts b/src/modules/models/interfaces.ts
@@ -0,0 +1,33 @@
+export interface SyncNode {
+	key: string;
+	type: 'collection' | 'item' | 'note';
+	title: string;
+	parentKey?: string;
+	children: SyncNode[];
+	raw?: unknown;
+}
+
+export interface SyncTree {
+	rootCollections: SyncNode[];
+	orphans: SyncNode[];
+	lookup: Record<string, SyncNode>;
+}
+
+export type SyncOp = {
+	op: 'create' | 'update' | 'move' | 'delete';
+	node?: SyncNode;
+	key?: string;
+	newParentKey?: string;
+};
+
+export function isCollectionNode(node: SyncNode): node is SyncNode & { type: 'collection' } {
+	return node.type === 'collection';
+}
+
+export function isItemNode(node: SyncNode): node is SyncNode & { type: 'item' } {
+	return node.type === 'item';
+}
+
+export function isNoteNode(node: SyncNode): node is SyncNode & { type: 'note' } {
+	return node.type === 'note';
+}
diff --git a/src/modules/models/powerups.ts b/src/modules/models/powerups.ts
@@ -0,0 +1,9 @@
+export enum Powerup {
+	ZITEM = 'ZITEM',
+	ZCOLL = 'ZCOLL',
+}
+
+export const itemTypeToPowerup: Record<string, Powerup> = {
+	item: Powerup.ZITEM,
+	collection: Powerup.ZCOLL,
+};
diff --git a/src/modules/storage/snapshotRepository.ts b/src/modules/storage/snapshotRepository.ts
@@ -0,0 +1,15 @@
+export interface Snapshot {
+	version: 1;
+	timestamp: number;
+	items: unknown[];
+	collections: unknown[];
+}
+
+export async function loadSnapshot(): Promise<Snapshot | null> {
+	// TODO: implement persistence
+	return null;
+}
+
+export async function saveSnapshot(data: Snapshot): Promise<void> {
+	// TODO: implement persistence
+}
diff --git a/src/modules/tree/__tests__/buildSyncTree.test.ts b/src/modules/tree/__tests__/buildSyncTree.test.ts
@@ -0,0 +1,7 @@
+import { buildSyncTree } from '../buildSyncTree';
+
+test.skip('buildSyncTree returns empty tree for empty data', () => {
+	// TODO implement
+	const tree = buildSyncTree({});
+	expect(tree.rootCollections).toEqual([]);
+});
diff --git a/src/modules/tree/buildSyncTree.ts b/src/modules/tree/buildSyncTree.ts
@@ -0,0 +1,10 @@
+import { SyncTree } from '../models/interfaces';
+
+export function buildSyncTree(data: unknown): SyncTree {
+  // TODO: extract real logic
+  return {
+    rootCollections: [],
+    orphans: [],
+    lookup: {},
+  };
+}
diff --git a/src/modules/ui/index.ts b/src/modules/ui/index.ts
@@ -0,0 +1,4 @@
+// TODO: move all UI code here
+export function initUI() {
+  // placeholder
+}
diff --git a/src/modules/utils/depth.ts b/src/modules/utils/depth.ts
@@ -0,0 +1,8 @@
+import { SyncNode } from '../models/interfaces';
+
+export function depth(node: SyncNode & { parent?: SyncNode; _depth?: number }): number {
+	if (node._depth !== undefined) return node._depth;
+	const d = node.parent ? depth(node.parent) + 1 : 0;
+	node._depth = d;
+	return d;
+}
diff --git a/src/modules/utils/hashJson.ts b/src/modules/utils/hashJson.ts
@@ -0,0 +1,6 @@
+import { createHash } from 'crypto';
+
+export function hashJsonSha256(value: unknown): string {
+	const json = JSON.stringify(value);
+	return createHash('sha256').update(json).digest('hex');
+}
diff --git a/src/modules/utils/slugify.ts b/src/modules/utils/slugify.ts
@@ -0,0 +1,6 @@
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/[^\w-]/g, '');
+}
diff --git a/test/fixtures/edge-case-library.json b/test/fixtures/edge-case-library.json
@@ -0,0 +1,4 @@
+{
+  "collections": [{"key": "root", "name": "Root", "parent": null}],
+  "items": [{"key": "i-edge", "title": "Edge & Item"}]
+}
diff --git a/test/fixtures/medium-library.json b/test/fixtures/medium-library.json
@@ -0,0 +1,4 @@
+{
+  "collections": [{"key": "1", "name": "Collection"}],
+  "items": [{"key": "i1", "title": "Item"}]
+}
diff --git a/test/fixtures/small-library.json b/test/fixtures/small-library.json
@@ -0,0 +1,4 @@
+{
+  "collections": [],
+  "items": []
+}
diff --git a/tsconfig.json b/tsconfig.json
diff --git a/typedoc.json b/typedoc.json
