prjct-cli 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [1.18.0] - 2026-02-09
+
+### Features
+
+- implement incremental sync with file hashing (PRJ-305) (#160)
+
+
+## [1.18.0] - 2026-02-09
+
+### Features
+
+- **Incremental sync**: `prjct sync` now only re-analyzes files that changed since last sync (PRJ-305)
+  - File hashing with Bun.hash (xxHash64) — <100ms for 500 files
+  - Change propagation through import graph (1-level reverse edges)
+  - Conditional index rebuilds: BM25, import graph, co-change only when source files change
+  - Conditional agent regeneration: only when config files (package.json, tsconfig.json) change
+  - `prjct sync --full` flag to force complete re-analysis
+
+### Implementation Details
+
+New modules:
+- `core/domain/file-hasher.ts` — Hash computation via Bun.hash, SQLite registry using `index_checksums` table, diff detection (added/modified/deleted/unchanged)
+- `core/domain/change-propagator.ts` — Import graph reverse-edge lookup for 1-level change propagation, domain classification for affected files
+
+Modified:
+- `core/services/sync-service.ts` — Incremental decision logic: detect changes → propagate → conditionally rebuild indexes and agents
+- `core/services/watch-service.ts` — Passes accumulated `changedFiles` to sync options
+- `core/types/project-sync.ts` — Added `full`, `changedFiles` to `SyncOptions` + `IncrementalInfo` result type
+- CLI chain (`core/index.ts` → `commands.ts` → `analysis.ts`) — Wired `--full` flag through
+
+### Learnings
+
+- Bun's `fs.readdir` with `withFileTypes` returns `Dirent<NonSharedBuffer>` — need `String()` cast for `.name`
+- Existing `index_checksums` SQLite table was already set up (PRJ-303) — zero schema changes needed
+- Import graph reverse edges (from PRJ-304) enable efficient 1-level propagation without rebuilding the graph
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync` on fresh project (no hash cache) — should behave as full sync
+2. Run `prjct sync` again without changes — should skip index rebuilds and agent regeneration
+3. Modify a `.ts` file, run `prjct sync` — should detect change and rebuild indexes
+4. Modify `package.json`, run `prjct sync` — should regenerate agents
+5. Run `prjct sync --full` — should force complete re-analysis
+6. Run `prjct watch`, change a file — should pass changedFiles to sync
+
+#### For Users
+**What changed:** `prjct sync` is now incremental by default.
+**How to use:** No changes needed. Use `prjct sync --full` to force complete re-analysis.
+**Breaking changes:** None
+
 ## [1.17.0] - 2026-02-09
 
 ### Features

package/core/__tests__/domain/change-propagator.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from 'bun:test'
+import { affectedDomains, propagateChanges } from '../../domain/change-propagator'
+import type { FileDiff } from '../../domain/file-hasher'
+
+describe('change-propagator', () => {
+  // =========================================================================
+  // propagateChanges
+  // =========================================================================
+
+  describe('propagateChanges', () => {
+    test('returns direct changes when no import graph exists', () => {
+      const diff: FileDiff = {
+        added: ['src/new.ts'],
+        modified: ['src/changed.ts'],
+        deleted: ['src/removed.ts'],
+        unchanged: ['src/same.ts'],
+      }
+
+      // Use a fake projectId that won't have a graph
+      const result = propagateChanges(diff, 'nonexistent-project')
+
+      expect(result.directlyChanged).toEqual(['src/new.ts', 'src/changed.ts'])
+      expect(result.affectedByImports).toEqual([])
+      expect(result.allAffected).toEqual(['src/new.ts', 'src/changed.ts'])
+      expect(result.deleted).toEqual(['src/removed.ts'])
+    })
+
+    test('empty diff returns empty propagation', () => {
+      const diff: FileDiff = {
+        added: [],
+        modified: [],
+        deleted: [],
+        unchanged: ['src/a.ts', 'src/b.ts'],
+      }
+
+      const result = propagateChanges(diff, 'nonexistent-project')
+
+      expect(result.directlyChanged).toEqual([])
+      expect(result.affectedByImports).toEqual([])
+      expect(result.allAffected).toEqual([])
+    })
+  })
+
+  // =========================================================================
+  // affectedDomains
+  // =========================================================================
+
+  describe('affectedDomains', () => {
+    test('detects frontend files', () => {
+      const domains = affectedDomains([
+        'src/components/Button.tsx',
+        'src/pages/Home.jsx',
+        'styles/main.css',
+      ])
+      expect(domains.has('frontend')).toBe(true)
+      expect(domains.has('uxui')).toBe(true)
+    })
+
+    test('detects backend files', () => {
+      const domains = affectedDomains(['core/services/auth.ts', 'core/domain/user.ts'])
+      expect(domains.has('backend')).toBe(true)
+    })
+
+    test('detects testing files', () => {
+      const domains = affectedDomains([
+        'core/__tests__/auth.test.ts',
+        'src/components/Button.spec.tsx',
+      ])
+      expect(domains.has('testing')).toBe(true)
+    })
+
+    test('detects devops files', () => {
+      const domains = affectedDomains(['Dockerfile', '.github/workflows/ci.yml'])
+      expect(domains.has('devops')).toBe(true)
+    })
+
+    test('detects database files', () => {
+      const domains = affectedDomains(['prisma/schema.prisma', 'db/migrations/001.sql'])
+      expect(domains.has('database')).toBe(true)
+    })
+
+    test('handles mixed domain files', () => {
+      const domains = affectedDomains([
+        'src/components/Form.tsx', // frontend + uxui
+        'core/services/api.ts', // backend
+        'Dockerfile', // devops
+        'core/__tests__/api.test.ts', // testing + backend
+      ])
+      expect(domains.has('frontend')).toBe(true)
+      expect(domains.has('backend')).toBe(true)
+      expect(domains.has('devops')).toBe(true)
+      expect(domains.has('testing')).toBe(true)
+    })
+
+    test('empty file list returns empty domains', () => {
+      const domains = affectedDomains([])
+      expect(domains.size).toBe(0)
+    })
+  })
+})

package/core/__tests__/domain/file-hasher.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, test } from 'bun:test'
+import path from 'node:path'
+import { computeHashes, diffHashes, type FileHash } from '../../domain/file-hasher'
+
+describe('file-hasher', () => {
+  // =========================================================================
+  // diffHashes
+  // =========================================================================
+
+  describe('diffHashes', () => {
+    const makeHash = (filePath: string, hash: string): FileHash => ({
+      path: filePath,
+      hash,
+      size: 100,
+      mtime: '2026-01-01T00:00:00.000Z',
+    })
+
+    test('detects added files', () => {
+      const current = new Map<string, FileHash>([
+        ['src/new-file.ts', makeHash('src/new-file.ts', 'xxh64:abc')],
+        ['src/existing.ts', makeHash('src/existing.ts', 'xxh64:def')],
+      ])
+      const stored = new Map<string, FileHash>([
+        ['src/existing.ts', makeHash('src/existing.ts', 'xxh64:def')],
+      ])
+
+      const diff = diffHashes(current, stored)
+      expect(diff.added).toEqual(['src/new-file.ts'])
+      expect(diff.modified).toEqual([])
+      expect(diff.unchanged).toEqual(['src/existing.ts'])
+      expect(diff.deleted).toEqual([])
+    })
+
+    test('detects modified files', () => {
+      const current = new Map<string, FileHash>([
+        ['src/changed.ts', makeHash('src/changed.ts', 'xxh64:new-hash')],
+      ])
+      const stored = new Map<string, FileHash>([
+        ['src/changed.ts', makeHash('src/changed.ts', 'xxh64:old-hash')],
+      ])
+
+      const diff = diffHashes(current, stored)
+      expect(diff.added).toEqual([])
+      expect(diff.modified).toEqual(['src/changed.ts'])
+      expect(diff.unchanged).toEqual([])
+      expect(diff.deleted).toEqual([])
+    })
+
+    test('detects deleted files', () => {
+      const current = new Map<string, FileHash>()
+      const stored = new Map<string, FileHash>([
+        ['src/removed.ts', makeHash('src/removed.ts', 'xxh64:abc')],
+      ])
+
+      const diff = diffHashes(current, stored)
+      expect(diff.added).toEqual([])
+      expect(diff.modified).toEqual([])
+      expect(diff.unchanged).toEqual([])
+      expect(diff.deleted).toEqual(['src/removed.ts'])
+    })
+
+    test('handles empty maps', () => {
+      const diff = diffHashes(new Map(), new Map())
+      expect(diff.added).toEqual([])
+      expect(diff.modified).toEqual([])
+      expect(diff.unchanged).toEqual([])
+      expect(diff.deleted).toEqual([])
+    })
+
+    test('handles first sync (no stored hashes)', () => {
+      const current = new Map<string, FileHash>([
+        ['src/a.ts', makeHash('src/a.ts', 'xxh64:1')],
+        ['src/b.ts', makeHash('src/b.ts', 'xxh64:2')],
+        ['src/c.ts', makeHash('src/c.ts', 'xxh64:3')],
+      ])
+      const stored = new Map<string, FileHash>()
+
+      const diff = diffHashes(current, stored)
+      expect(diff.added).toHaveLength(3)
+      expect(diff.modified).toEqual([])
+      expect(diff.unchanged).toEqual([])
+      expect(diff.deleted).toEqual([])
+    })
+
+    test('mixed changes: added + modified + deleted + unchanged', () => {
+      const current = new Map<string, FileHash>([
+        ['src/new.ts', makeHash('src/new.ts', 'xxh64:new')],
+        ['src/changed.ts', makeHash('src/changed.ts', 'xxh64:v2')],
+        ['src/same.ts', makeHash('src/same.ts', 'xxh64:same')],
+      ])
+      const stored = new Map<string, FileHash>([
+        ['src/changed.ts', makeHash('src/changed.ts', 'xxh64:v1')],
+        ['src/same.ts', makeHash('src/same.ts', 'xxh64:same')],
+        ['src/gone.ts', makeHash('src/gone.ts', 'xxh64:gone')],
+      ])
+
+      const diff = diffHashes(current, stored)
+      expect(diff.added).toEqual(['src/new.ts'])
+      expect(diff.modified).toEqual(['src/changed.ts'])
+      expect(diff.unchanged).toEqual(['src/same.ts'])
+      expect(diff.deleted).toEqual(['src/gone.ts'])
+    })
+  })
+
+  // =========================================================================
+  // computeHashes (integration — reads actual files)
+  // =========================================================================
+
+  describe('computeHashes', () => {
+    test('computes hashes for project files', async () => {
+      // Hash the prjct-cli project itself (small subset)
+      const projectPath = path.resolve(__dirname, '..', '..', '..')
+      const hashes = await computeHashes(projectPath)
+
+      // Should find many files
+      expect(hashes.size).toBeGreaterThan(50)
+
+      // Check a known file exists
+      const packageJson = hashes.get('package.json')
+      expect(packageJson).toBeDefined()
+      expect(packageJson!.hash).toMatch(/^(xxh64|fnv1a):/)
+      expect(packageJson!.size).toBeGreaterThan(0)
+    })
+
+    test('excludes node_modules and .git', async () => {
+      const projectPath = path.resolve(__dirname, '..', '..', '..')
+      const hashes = await computeHashes(projectPath)
+
+      for (const [filePath] of hashes) {
+        expect(filePath).not.toContain('node_modules')
+        expect(filePath).not.toContain('.git/')
+      }
+    })
+
+    test('hash is deterministic', async () => {
+      const projectPath = path.resolve(__dirname, '..', '..', '..')
+      const hashes1 = await computeHashes(projectPath)
+      const hashes2 = await computeHashes(projectPath)
+
+      // Same file should produce same hash
+      const pkg1 = hashes1.get('package.json')
+      const pkg2 = hashes2.get('package.json')
+      expect(pkg1?.hash).toBe(pkg2?.hash)
+    })
+  })
+})

package/core/commands/analysis.ts

@@ -235,6 +235,7 @@ export class AnalysisCommands extends PrjctCommandsBase {
       yes?: boolean
       json?: boolean
       package?: string
+      full?: boolean
     } = {}
   ): Promise<CommandResult> {
     try {
@@ -308,7 +309,10 @@ export class AnalysisCommands extends PrjctCommandsBase {
         }
 
         // Do a dry-run sync to see what would change
-        const result = await syncService.sync(projectPath, { aiTools: options.aiTools })
+        const result = await syncService.sync(projectPath, {
+          aiTools: options.aiTools,
+          full: options.full,
+        })
 
         if (!result.success) {
           if (isNonInteractive) {
@@ -453,7 +457,10 @@ export class AnalysisCommands extends PrjctCommandsBase {
       out.spin('Syncing project...')
 
       // Use syncService to do EVERYTHING in one call
-      const result = await syncService.sync(projectPath, { aiTools: options.aiTools })
+      const result = await syncService.sync(projectPath, {
+        aiTools: options.aiTools,
+        full: options.full,
+      })
 
       if (!result.success) {
         out.fail(result.error || 'Sync failed')

package/core/commands/command-data.ts

@@ -166,11 +166,13 @@ export const COMMANDS: CommandMeta[] = [
     name: 'sync',
     group: 'core',
     description: 'Sync project state and update workflow agents',
-    usage: { claude: '/p:sync', terminal: 'prjct sync [--package=<name>]' },
+    usage: { claude: '/p:sync', terminal: 'prjct sync [--package=<name>] [--full]' },
     implemented: true,
     hasTemplate: true,
     requiresProject: true,
     features: [
+      'Incremental sync: only re-analyzes changed files (default)',
+      'Force full sync: --full bypasses incremental cache',
       'Monorepo support: --package=<name> for single package sync',
       'Nested PRJCT.md inheritance',
       'Per-package CLAUDE.md generation',

package/core/commands/commands.ts

@@ -211,6 +211,7 @@ class PrjctCommands {
       yes?: boolean
       json?: boolean
       package?: string
+      full?: boolean
     } = {}
   ): Promise<CommandResult> {
     return this.analysis.sync(projectPath, options)

package/core/domain/change-propagator.ts

@@ -0,0 +1,162 @@
+/**
+ * Change Propagator — Import-Based Change Detection
+ *
+ * When a file changes, files that import it may also need re-analysis.
+ * Uses the import graph (PRJ-304) to propagate changes 1 level deep
+ * through the reverse dependency chain.
+ *
+ * Example: If `auth.ts` changes, and `user-service.ts` imports `auth.ts`,
+ * then `user-service.ts` is also marked as "affected" even though its
+ * content hash didn't change.
+ *
+ * @module domain/change-propagator
+ * @version 1.0.0
+ */
+
+import type { FileDiff } from './file-hasher'
+import { loadGraph } from './import-graph'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface PropagatedChanges {
+  /** Files that changed directly (added + modified from hash diff) */
+  directlyChanged: string[]
+  /** Files that import a directly changed file (1 level deep) */
+  affectedByImports: string[]
+  /** Union of directlyChanged + affectedByImports (deduplicated) */
+  allAffected: string[]
+  /** Files that were deleted */
+  deleted: string[]
+}
+
+// =============================================================================
+// Propagation
+// =============================================================================
+
+/**
+ * Given a file diff, propagate changes through the import graph.
+ *
+ * For each changed file, find all files that import it (reverse edges)
+ * at depth 1. These "affected" files should be re-analyzed because
+ * their imports have changed behavior.
+ *
+ * @param diff - The raw file diff from hash comparison
+ * @param projectId - Project ID for loading the import graph
+ * @returns Propagated changes including affected importers
+ */
+export function propagateChanges(diff: FileDiff, projectId: string): PropagatedChanges {
+  const directlyChanged = [...diff.added, ...diff.modified]
+  const directSet = new Set(directlyChanged)
+  const affected = new Set<string>()
+
+  // Try to load import graph for reverse-edge lookup
+  const graph = loadGraph(projectId)
+
+  if (graph) {
+    // For each directly changed file, find its reverse edges (files that import it)
+    for (const changedFile of directlyChanged) {
+      const importers = graph.reverse[changedFile]
+      if (importers) {
+        for (const importer of importers) {
+          // Only add if not already directly changed
+          if (!directSet.has(importer)) {
+            affected.add(importer)
+          }
+        }
+      }
+    }
+  }
+
+  const affectedByImports = Array.from(affected)
+  const allAffected = [...directlyChanged, ...affectedByImports]
+
+  return {
+    directlyChanged,
+    affectedByImports,
+    deleted: diff.deleted,
+    allAffected,
+  }
+}
+
+/**
+ * Determine which domain agents need regeneration based on changed files.
+ *
+ * Maps file extensions and paths to domains:
+ * - .tsx/.jsx/.css/.scss/.html/.vue/.svelte → frontend
+ * - .ts/.js (non-test, non-config) → backend
+ * - .test.ts/.spec.ts → testing
+ * - Dockerfile/.dockerignore → devops
+ * - .sql/prisma/drizzle → database
+ *
+ * Returns the set of domain names that have affected files.
+ */
+export function affectedDomains(changedFiles: string[]): Set<string> {
+  const domains = new Set<string>()
+
+  for (const file of changedFiles) {
+    const lower = file.toLowerCase()
+
+    // Frontend indicators
+    if (
+      lower.endsWith('.tsx') ||
+      lower.endsWith('.jsx') ||
+      lower.endsWith('.css') ||
+      lower.endsWith('.scss') ||
+      lower.endsWith('.vue') ||
+      lower.endsWith('.svelte') ||
+      lower.includes('/components/') ||
+      lower.includes('/pages/') ||
+      lower.includes('/app/')
+    ) {
+      domains.add('frontend')
+      domains.add('uxui')
+    }
+
+    // Testing indicators
+    if (
+      lower.includes('.test.') ||
+      lower.includes('.spec.') ||
+      lower.includes('__tests__') ||
+      lower.includes('/test/')
+    ) {
+      domains.add('testing')
+    }
+
+    // DevOps indicators
+    if (
+      lower.includes('dockerfile') ||
+      lower.includes('docker-compose') ||
+      lower.includes('.dockerignore') ||
+      lower.includes('.github/') ||
+      lower.includes('ci/') ||
+      lower.includes('cd/')
+    ) {
+      domains.add('devops')
+    }
+
+    // Database indicators
+    if (
+      lower.endsWith('.sql') ||
+      lower.includes('prisma') ||
+      lower.includes('drizzle') ||
+      lower.includes('migration') ||
+      lower.includes('/db/')
+    ) {
+      domains.add('database')
+    }
+
+    // Backend indicators (TypeScript/JavaScript that isn't clearly frontend/test)
+    if (
+      (lower.endsWith('.ts') || lower.endsWith('.js')) &&
+      !lower.includes('.test.') &&
+      !lower.includes('.spec.') &&
+      !lower.endsWith('.d.ts')
+    ) {
+      domains.add('backend')
+    }
+  }
+
+  return domains
+}