studiograph 1.3.47 → 1.3.48-beta.1

package/dist/services/graph-maintenance.js

@@ -0,0 +1,143 @@
+/**
+ * Graph Maintenance Service
+ *
+ * Proactive graph health analysis: aggregates lint issues, orphan entities,
+ * stale entities, and broken wikilinks into a unified health report.
+ * Designed to run periodically or on-demand, with results surfaced
+ * in the dashboard digest.
+ */
+import { lintWorkspace } from './lint-service.js';
+import { findOrphans } from './orphan-service.js';
+// ── Configuration ─────────────────────────────────────────────────────
+const STALE_THRESHOLD_DAYS = 30;
+const MAX_ISSUES_PER_CATEGORY = 20;
+// ── Service ───────────────────────────────────────────────────────────
+export async function analyzeGraphHealth(manager) {
+    const missingFields = await lintWorkspace(manager);
+    const orphans = await findOrphansWrapped(manager);
+    const stale = findStaleEntities(manager);
+    const brokenLinks = findBrokenWikilinks(manager);
+    let totalEntities = 0;
+    for (const repo of manager.getAllRepoConfigs()) {
+        try {
+            const graph = manager.getGraph(repo.name);
+            const all = graph.search({});
+            totalEntities += all.length;
+        }
+        catch { /* skip */ }
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        summary: {
+            totalEntities,
+            totalIssues: missingFields.length + orphans.length + stale.length + brokenLinks.length,
+            missingFields: missingFields.length,
+            orphanEntities: orphans.length,
+            staleEntities: stale.length,
+            brokenWikilinks: brokenLinks.length,
+        },
+        missingFields: missingFields.slice(0, MAX_ISSUES_PER_CATEGORY),
+        orphans: orphans.slice(0, MAX_ISSUES_PER_CATEGORY),
+        stale: stale.slice(0, MAX_ISSUES_PER_CATEGORY),
+        brokenLinks: brokenLinks.slice(0, MAX_ISSUES_PER_CATEGORY),
+    };
+}
+// ── Orphan detection wrapper ──────────────────────────────────────────
+async function findOrphansWrapped(manager) {
+    try {
+        const result = await findOrphans(manager, {});
+        return result.orphans ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+// ── Stale entity detection ────────────────────────────────────────────
+function findStaleEntities(manager) {
+    const stale = [];
+    const now = Date.now();
+    const thresholdMs = STALE_THRESHOLD_DAYS * 24 * 60 * 60 * 1000;
+    for (const repo of manager.getAllRepoConfigs()) {
+        let graph;
+        try {
+            graph = manager.getGraph(repo.name);
+        }
+        catch {
+            continue;
+        }
+        const entities = graph.search({});
+        for (const entity of entities) {
+            const data = entity.data;
+            const updatedAt = data?.updated_at;
+            if (!updatedAt)
+                continue;
+            const updatedTime = new Date(updatedAt).getTime();
+            if (isNaN(updatedTime))
+                continue;
+            const daysSince = Math.floor((now - updatedTime) / (24 * 60 * 60 * 1000));
+            if (daysSince >= STALE_THRESHOLD_DAYS) {
+                stale.push({
+                    repo: repo.name,
+                    entityType: data.entity_type ?? entity.entityType,
+                    entityId: entity.id,
+                    name: data.name ?? entity.id,
+                    lastUpdated: updatedAt,
+                    daysSinceUpdate: daysSince,
+                });
+            }
+        }
+    }
+    // Sort by staleness (most stale first)
+    stale.sort((a, b) => b.daysSinceUpdate - a.daysSinceUpdate);
+    return stale;
+}
+// ── Broken wikilink detection ─────────────────────────────────────────
+function findBrokenWikilinks(manager) {
+    const broken = [];
+    // Build a set of all known entity IDs across the workspace
+    const allEntityIds = new Set();
+    for (const repo of manager.getAllRepoConfigs()) {
+        try {
+            const graph = manager.getGraph(repo.name);
+            const entities = graph.search({});
+            for (const e of entities) {
+                allEntityIds.add(e.id);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    // Check wikilinks in each entity
+    for (const repo of manager.getAllRepoConfigs()) {
+        let graph;
+        try {
+            graph = manager.getGraph(repo.name);
+        }
+        catch {
+            continue;
+        }
+        const entities = graph.search({});
+        for (const entity of entities) {
+            const wikilinks = entity.document?.wikilinks ?? [];
+            const data = entity.data;
+            for (const link of wikilinks) {
+                // Normalize: strip [[ ]] if present
+                const target = link.replace(/^\[\[|\]\]$/g, '').trim();
+                if (!target)
+                    continue;
+                if (!allEntityIds.has(target)) {
+                    broken.push({
+                        repo: repo.name,
+                        entityType: data?.entity_type ?? entity.entityType,
+                        entityId: entity.id,
+                        name: data?.name ?? entity.id,
+                        brokenLink: target,
+                    });
+                }
+            }
+        }
+    }
+    return broken;
+}
+//# sourceMappingURL=graph-maintenance.js.map

package/dist/services/graph-maintenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-maintenance.js","sourceRoot":"","sources":["../../src/services/graph-maintenance.ts"],"names":[],"mappings":"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"}

package/dist/services/import-service.d.ts

@@ -1,25 +1,68 @@
 /**
  * File Import Service
  *
- * Converts external files (markdown, text, CSV) into Studiograph entities.
+ * Converts external files into Studiograph entities.
  * - .md → note entity (parses frontmatter if present)
  * - .txt → note entity (plain text as body)
  * - .csv → dataset entity (infers column schema)
+ * - .pdf → note entity (extracts text via pdf-parse)
+ *
+ * A .csv dropped here becomes a structured `dataset` entity (in-graph,
+ * queryable, editable in the grid). Uploading a .csv through the asset
+ * upload UI instead lands it as an opaque `asset` with
+ * `asset_kind: spreadsheet` — the two paths coexist.
  */
 import { BaseGraphManager } from '../core/graph.js';
+import type { GitUser } from './git.js';
 export interface ImportResult {
     entityId: string;
     entityType: string;
     status: 'created' | 'skipped' | 'error';
     error?: string;
+    /** Absolute path of the written file. Set when status === 'created' so
+     *  batch callers can collect paths to commit in one transaction.
+     *  Undefined for 'skipped' / 'error'. */
+    path?: string;
+    /** Absolute paths of any per-folder display-name sidecars written for this
+     *  import (one per source-segment that carried casing the slug fallback
+     *  can't recover). Empty when the source path was already kebab. Batch
+     *  callers should pass these to commitPending() under `extraPaths` so the
+     *  sidecars land in the same commit as the entity files. */
+    sidecarPaths?: string[];
 }
 export interface ImportOptions {
     entityType?: string;
     entityId?: string;
+    /** Override commit author. When omitted, the import is committed under
+     *  whatever default identity the underlying git service uses. */
+    user?: GitUser;
+    /** Repo-relative folder to create the entry in. Empty/undefined = repo
+     *  root. Mirrors graph.create's folderPath option. */
+    folderPath?: string;
+    /** Commit message override. Defaults to a sensible auto-generated one. */
+    commitMessage?: string;
+    /** Defer the git commit. Defaults to true (preserves existing behavior
+     *  where the agent tool batches commits). HTTP callers should pass false
+     *  so each import lands as its own commit. */
+    skipCommit?: boolean;
 }
 export declare function isSupportedFile(filename: string): boolean;
+/**
+ * Extract text content from a file for agent processing.
+ * Handles text-based formats directly and binary formats (PDF) via extraction libraries.
+ */
+export declare function extractText(filename: string, content: string): Promise<string>;
 /**
  * Import a single file as a Studiograph entity.
- * Does NOT commit — caller should commit after batch imports.
+ *
+ * The `filename` may include a relative directory portion (e.g.
+ * `decks/2025-q1/talk.md`); the directory is slugified and combined with
+ * `options.folderPath` (the caller's chosen destination subfolder) to
+ * produce the final on-disk location. This preserves user-organized
+ * folder structure when a folder is dropped onto the import zone.
+ *
+ * Collisions on `(entity_type, entity_id)` are auto-suffixed (`talk` →
+ * `talk-2` → `talk-3` …) rather than skipped, so dropping a folder twice
+ * never silently swallows files.
  */
 export declare function importFile(graph: BaseGraphManager, filename: string, content: Buffer | string, options?: ImportOptions): Promise<ImportResult>;