@untangle-code/file-graph 0.0.0-stage → 0.1.0

package/dist/paths.js

@@ -0,0 +1,129 @@
+/**
+ * Pfadhilfen des Dateigraphen — ausschliesslich POSIX, ausschliesslich
+ * repo-relativ.
+ *
+ * Warum eigene Helfer statt `node:path`: der Dateigraph rechnet nie auf
+ * Betriebssystempfaden. Er kennt nur `"/"`-normalisierte, repo-relative
+ * Pfade (spec.md §5.4), und `node:path` auf Windows wuerde aus `a/b`
+ * beim Zusammensetzen `a\b` machen — damit haette dieselbe Codebasis auf
+ * zwei Maschinen zwei verschiedene `file_id`s. `node:path/posix` deckt
+ * einen Teil ab, liefert aber `".."`-Ergebnisse ausserhalb der Wurzel
+ * still zurueck; hier wird das zu `null` und damit zu einem benannten
+ * Fehlschlag (E4).
+ */
+/** Normalisiert Trennzeichen und entfernt fuehrende `"./"` sowie Mehrfachslashes. */
+export function normalizePath(path) {
+    const forward = path.replace(/\\/g, "/");
+    const collapsed = forward.replace(/\/{2,}/g, "/");
+    const withoutLeadingDot = collapsed.startsWith("./") ? collapsed.slice(2) : collapsed;
+    const withoutLeadingSlash = withoutLeadingDot.startsWith("/")
+        ? withoutLeadingDot.slice(1)
+        : withoutLeadingDot;
+    return withoutLeadingSlash.endsWith("/") && withoutLeadingSlash.length > 1
+        ? withoutLeadingSlash.slice(0, -1)
+        : withoutLeadingSlash;
+}
+/** Verzeichnisanteil eines repo-relativen Pfades; `""` fuer Dateien in der Wurzel. */
+export function dirnameOf(path) {
+    const normalized = normalizePath(path);
+    const index = normalized.lastIndexOf("/");
+    return index === -1 ? "" : normalized.slice(0, index);
+}
+/** Dateiname ohne Verzeichnisanteil. */
+export function basenameOf(path) {
+    const normalized = normalizePath(path);
+    const index = normalized.lastIndexOf("/");
+    return index === -1 ? normalized : normalized.slice(index + 1);
+}
+/** Erweiterung inklusive Punkt, kleingeschrieben; `""` bei Dotfiles und ohne Punkt. */
+export function extensionOf(path) {
+    const name = basenameOf(path);
+    const index = name.lastIndexOf(".");
+    if (index <= 0) {
+        return "";
+    }
+    return name.slice(index).toLowerCase();
+}
+/**
+ * Setzt einen Basispfad und ein Segment zusammen und loest `.`/`..` auf.
+ *
+ * Gibt `null` zurueck, wenn die Aufloesung ueber die Repositorywurzel
+ * hinauslaeuft. Ein Import wie `"../../../../etc/passwd"` aus `src/a.ts`
+ * ist damit ein benannter Fehlschlag und kein still auf `etc/passwd`
+ * gekuerzter Treffer.
+ */
+export function joinRelative(baseDir, segment) {
+    const base = normalizePath(baseDir);
+    const parts = base === "" ? [] : base.split("/");
+    const stack = [...parts];
+    for (const raw of normalizePath(segment).split("/")) {
+        if (raw === "" || raw === ".") {
+            continue;
+        }
+        if (raw === "..") {
+            if (stack.length === 0) {
+                return null;
+            }
+            stack.pop();
+            continue;
+        }
+        stack.push(raw);
+    }
+    return stack.join("/");
+}
+/** True, wenn `path` unterhalb von `directory` liegt (oder gleich ist). */
+export function isWithin(directory, path) {
+    const dir = normalizePath(directory);
+    const target = normalizePath(path);
+    if (dir === "" || dir === ".") {
+        return true;
+    }
+    return target === dir || target.startsWith(`${dir}/`);
+}
+/**
+ * Pfad von `path` relativ zu `directory`; `null`, wenn `path` nicht darunter
+ * liegt. Bewusst kein `..`-Ergebnis: der Aufrufer will hier wissen, ob etwas
+ * INNERHALB eines Verzeichnisses liegt, nicht wie man hinaufkommt.
+ */
+export function relativeWithin(directory, path) {
+    if (!isWithin(directory, path)) {
+        return null;
+    }
+    const dir = normalizePath(directory);
+    const target = normalizePath(path);
+    if (dir === "" || dir === ".") {
+        return target;
+    }
+    return target === dir ? "" : target.slice(dir.length + 1);
+}
+/** True fuer `"./x"`, `"../x"` und `"."`/`".."` selbst. */
+export function isRelativeSpecifier(specifier) {
+    return specifier === "." || specifier === ".." || /^\.\.?\//.test(specifier);
+}
+/**
+ * Normalisiert nur die Trennzeichen und laesst einen fuehrenden `"/"` stehen.
+ *
+ * `normalizePath` ist fuer REPO-RELATIVE Pfade gedacht und entfernt deshalb
+ * einen fuehrenden Schraegstrich. Auf einen absoluten Wurzelpfad angewandt
+ * wuerde daraus ein relativer — und jeder Lesezugriff ginge ins Leere. Fuer
+ * absolute Pfade (Repositorywurzeln, Eintraege des Dateisystemports) gilt
+ * diese Funktion.
+ */
+export function normalizeSeparators(path) {
+    const forward = path.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
+    return forward.length > 1 && forward.endsWith("/") ? forward.slice(0, -1) : forward;
+}
+/**
+ * Pfad von `path` relativ zur absoluten Wurzel `root`; `null`, wenn `path`
+ * nicht darunter liegt. Beide Angaben sind absolut.
+ */
+export function relativeToRoot(root, path) {
+    const normalizedRoot = normalizeSeparators(root);
+    const normalizedPath = normalizeSeparators(path);
+    if (normalizedPath === normalizedRoot) {
+        return "";
+    }
+    const prefix = normalizedRoot.endsWith("/") ? normalizedRoot : `${normalizedRoot}/`;
+    return normalizedPath.startsWith(prefix) ? normalizedPath.slice(prefix.length) : null;
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,qFAAqF;AACrF,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAClD,MAAM,iBAAiB,GAAG,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtF,MAAM,mBAAmB,GAAG,iBAAiB,CAAC,UAAU,CAAC,GAAG,CAAC;QAC3D,CAAC,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5B,CAAC,CAAC,iBAAiB,CAAC;IACtB,OAAO,mBAAmB,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC;QACxE,CAAC,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAClC,CAAC,CAAC,mBAAmB,CAAC;AAC1B,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1C,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AACxD,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1C,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACf,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,OAAe;IAC3D,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjD,MAAM,KAAK,GAAa,CAAC,GAAG,KAAK,CAAC,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACpD,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;YAC9B,SAAS;QACX,CAAC;QACD,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvB,OAAO,IAAI,CAAC;YACd,CAAC;YACD,KAAK,CAAC,GAAG,EAAE,CAAC;YACZ,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,QAAQ,CAAC,SAAiB,EAAE,IAAY;IACtD,MAAM,GAAG,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,IAAY;IAC5D,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,GAAG,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;QAC9B,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,OAAO,SAAS,KAAK,GAAG,IAAI,SAAS,KAAK,IAAI,IAAI,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACjE,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AACtF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,IAAY;IACvD,MAAM,cAAc,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACjD,MAAM,cAAc,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,cAAc,KAAK,cAAc,EAAE,CAAC;QACtC,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,MAAM,GAAG,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,GAAG,CAAC;IACpF,OAAO,cAAc,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACxF,CAAC"}

package/dist/persistence.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Ablage des Dateigraphen ueber den BESTEHENDEN `GraphStore`-Port
+ * (domain `ports.ts`, architecture.md §6.11, §11.6).
+ *
+ * ENTSCHEIDUNG: Dieses Paket definiert KEINEN eigenen Speicher-Port. Der
+ * `GraphStore` von `domain` hat mit `graph_files`, `graph_indices` und
+ * `graph_meta` genau die drei Sammlungen, die ein Dateigraph braucht, und es
+ * gibt bereits eine Kontraktsuite (`@untangle-code/testkit`,
+ * `runGraphStoreContract`) plus zwei Adapter dagegen. Ein zweiter Port haette
+ * dieselbe Semantik ein zweites Mal beschrieben und beide Adapter zur
+ * Doppelimplementierung gezwungen.
+ *
+ * SHARD-AUFTEILUNG:
+ * - `graph_meta` / `<workspace>:meta` — Metriken, Topologie, Skip-Ledger, Knotenzahl;
+ * - `graph_files` / `<workspace>:file:<file_id>` — ein Knoten samt seiner Kanten;
+ * - `graph_indices` / `<workspace>:by-path` — Repository + Pfad → `file_id`.
+ *
+ * Ein Shard je Datei (statt eines Riesenshards) ist Absicht: die inkrementelle
+ * Fortschreibung schreibt dann genau die Dateien zurueck, die sie neu gerechnet
+ * hat.
+ */
+import type { GraphShardV1, GraphStore, PortCallOptions } from "@untangle-code/domain";
+import type { FileGraphSnapshotV1 } from "./types.js";
+/** Vor Wave 8 verwendete globale Metadaten-ID; nur fuer expliziten Legacy-Fallback. */
+export declare const META_SHARD_ID = "meta";
+/** Vor Wave 8 verwendete globale Pfadindex-ID; nur fuer expliziten Legacy-Fallback. */
+export declare const PATH_INDEX_SHARD_ID = "by-path";
+/** Versionierter Praefix der workspace-sicheren Dateigraph-Shards. */
+export declare const FILE_GRAPH_SHARD_NAMESPACE = "untangle:file-graph:v1";
+/** Der vollstaendige Geltungsbereich eines persistierten Graphabbilds. */
+export interface GraphSnapshotScope {
+    workspaceId: string;
+    generationId: string;
+}
+/** Opt-in fuer das Lesen vor Wave 8 erzeugter, nicht namespaceter Shards. */
+export interface GraphSnapshotReadOptions extends PortCallOptions {
+    /**
+     * Nur ein explizites `true` aktiviert den Legacy-Pfad. Auch dann wird der
+     * gelesene Payload strikt gegen `workspaceId` UND `generationId` geprueft.
+     */
+    allowLegacyFallback?: boolean;
+}
+/** Praefix aller Dateigraph-Shards eines Workspace. */
+export declare function fileGraphWorkspaceShardPrefix(workspaceId: string): string;
+/** Namespacete ID des Metadaten-Shards. */
+export declare function fileGraphMetaShardId(workspaceId: string): string;
+/** Namespacete ID des Pfadindex-Shards. */
+export declare function fileGraphPathIndexShardId(workspaceId: string): string;
+/** Namespacete ID eines Datei-Shards. */
+export declare function fileGraphFileShardId(workspaceId: string, fileId: string): string;
+/** Erzeugt alle Shards eines Abbilds, in stabiler Reihenfolge. */
+export declare function toGraphShards(snapshot: FileGraphSnapshotV1, writeId: string): GraphShardV1[];
+/** Schreibt ein vollstaendiges Abbild in den Speicher. */
+export declare function writeGraphSnapshot(store: GraphStore, snapshot: FileGraphSnapshotV1, writeId: string, options?: PortCallOptions): Promise<void>;
+/**
+ * Fehler beim Zurueckladen — als Wert, damit der Aufrufer ihn ins Ledger legen
+ * kann.
+ *
+ * `missing_path_index` und `count_mismatch` sind KEINE Zierde: ohne sie
+ * verlaeuft der haeufigste Verlustfall (ein Datei-Shard ist nicht mehr da und
+ * wird deshalb auch nicht mehr aufgezaehlt) voellig geraeuschlos. Der
+ * Pfadindex und die im Metadaten-Shard mitgeschriebenen Sollzahlen sind die
+ * beiden unabhaengigen Zeugen dafuer, WIE VIEL da sein muesste.
+ */
+export interface SnapshotReadIssue {
+    kind: "missing_meta" | "missing_path_index" | "missing_file_shard" | "malformed_payload" | "count_mismatch" | "workspace_scope_required" | "scope_mismatch";
+    message: string;
+}
+export interface SnapshotReadResult {
+    snapshot: FileGraphSnapshotV1 | null;
+    issues: SnapshotReadIssue[];
+}
+/**
+ * Laedt ein Abbild fuer GENAU einen Workspace und GENAU eine Generation.
+ *
+ * Die alte Signatur `(store, generationId)` bleibt absichtlich typkompatibel,
+ * liest aber nichts mehr: ohne Workspace kann kein gespeicherter Graph sicher
+ * zugeordnet werden. Alte, globale Shards werden nur ueber
+ * `allowLegacyFallback: true` gelesen, nachdem ein vollstaendiger Scope
+ * angegeben wurde; jeder Payload wird dabei gegen diesen Scope geprueft.
+ */
+export declare function readGraphSnapshot(store: GraphStore, scope: GraphSnapshotScope | string, options?: GraphSnapshotReadOptions): Promise<SnapshotReadResult>;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAGV,YAAY,EACZ,UAAU,EACV,eAAe,EAChB,MAAM,uBAAuB,CAAC;AAK/B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,uFAAuF;AACvF,eAAO,MAAM,aAAa,SAAS,CAAC;AACpC,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAC7C,sEAAsE;AACtE,eAAO,MAAM,0BAA0B,2BAA2B,CAAC;AAEnE,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,6EAA6E;AAC7E,MAAM,WAAW,wBAAyB,SAAQ,eAAe;IAC/D;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,uDAAuD;AACvD,wBAAgB,6BAA6B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED,2CAA2C;AAC3C,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,2CAA2C;AAC3C,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,yCAAyC;AACzC,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,QAAQ,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAsF5F;AAED,0DAA0D;AAC1D,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EACA,cAAc,GACd,oBAAoB,GACpB,oBAAoB,GACpB,mBAAmB,GACnB,gBAAgB,GAChB,0BAA0B,GAC1B,gBAAgB,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACrC,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAgDD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,kBAAkB,GAAG,MAAM,EAClC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,kBAAkB,CAAC,CA4C7B"}