feat: enhance deptrac image generation with change detection

Author: TerrorSquad

booster/.husky/shared/extras.ts

@@ -10,6 +10,36 @@ export interface ArtifactResult {
   path?: string
 }
 
+/**
+ * Check if deptrac.png was freshly written and whether it differs from git HEAD.
+ *
+ * @param mtimeBefore - mtime of the file before deptrac ran (0 if it didn't exist)
+ * @returns ArtifactResult with generated=true if freshly written, changed=true if content differs from git
+ */
+async function checkDeptracImage(mtimeBefore: number): Promise<ArtifactResult> {
+  if (!(await fs.pathExists('./deptrac.png'))) {
+    return { generated: false, changed: false }
+  }
+
+  const mtimeAfter = (await fs.stat('./deptrac.png')).mtimeMs
+  if (mtimeAfter <= mtimeBefore) {
+    // File was not rewritten during this run — stale from a previous run
+    return { generated: false, changed: false }
+  }
+
+  // File was freshly generated. Check if content differs from what's in git.
+  try {
+    const diffResult = await exec(['git', 'diff', '--name-only', '--', 'deptrac.png'], {
+      quiet: true,
+    })
+    const changed = diffResult.toString().trim().includes('deptrac.png')
+    return { generated: true, changed, path: 'deptrac.png' }
+  } catch {
+    // git diff can fail if the file is untracked; treat as changed
+    return { generated: true, changed: true, path: 'deptrac.png' }
+  }
+}
+
 /**
  * Generate Deptrac architecture diagram
  *
@@ -23,21 +53,34 @@ export async function generateDeptracImage(): Promise<ArtifactResult> {
     return { generated: false, changed: false }
   }
 
-  try {
-    log.tool('Deptrac', 'Generating architecture diagram...')
+  log.tool('Deptrac', 'Generating architecture diagram...')
+
+  // Capture mtime before running so we can detect if the file was (re)written
+  const mtimeBefore = (await fs.pathExists('./deptrac.png'))
+    ? (await fs.stat('./deptrac.png')).mtimeMs
+    : 0
 
+  try {
     await exec(
       ['./vendor/bin/deptrac', '--formatter=graphviz-image', '--output=deptrac.png'],
       { type: 'php' },
     )
 
-    if (await fs.pathExists('./deptrac.png')) {
-      log.success('Deptrac image generated: deptrac.png')
-      return { generated: true, changed: true, path: 'deptrac.png' }
+    const result = await checkDeptracImage(mtimeBefore)
+    if (result.generated) {
+      log.success(`Deptrac image generated${result.changed ? '' : ' (unchanged)'}: deptrac.png`)
     }
-
-    return { generated: false, changed: false }
+    return result
   } catch (error: unknown) {
+    // Deptrac exits with code 1 when violations are found, but still generates the image.
+    // Check if the file was freshly written despite the non-zero exit.
+    const result = await checkDeptracImage(mtimeBefore)
+    if (result.generated) {
+      const status = result.changed ? '' : ' (unchanged)'
+      log.success(`Deptrac image generated (violations found)${status}: deptrac.png`)
+      return result
+    }
+
     const errorMessage = error instanceof Error ? error.message : String(error)
     log.warn(`Deptrac image generation failed: ${errorMessage}`)
     return { generated: false, changed: false }