canopycms 0.0.67-int.90 → 0.0.67

package/dist/content-id-index.d.ts

@@ -7,10 +7,9 @@ export interface IdLocation {
     slug?: Slug;
 }
 /**
- * A group of on-disk filenames whose names embed the same content ID,
- * discovered by {@link ContentIdIndex.buildFromFilenames}. See the class doc
- * comment's "Duplicate-ID quarantine" section for how `keptPath` is chosen
- * and why it is deterministic across hosts.
+ * A group of on-disk filenames embedding the same content ID, discovered by
+ * {@link ContentIdIndex.buildFromFilenames}. Its doc comment covers how
+ * `keptPath` is chosen and why every host chooses the same one.
  */
 export interface DuplicateContentId {
     id: ContentId;
@@ -20,166 +19,84 @@ export interface DuplicateContentId {
     droppedPaths: PhysicalPath[];
 }
 /**
- * ContentIdIndex manages the bidirectional mapping between content IDs and file paths.
- *
- * IDs are embedded in filenames using the patterns:
- * - Entries: `{type}.{slug}.{12-char-id}.{ext}` (e.g., `post.dune.a1b2c3d4e5f6.json`)
- * - Collection directories: `{slug}.{12-char-id}/` (e.g., `posts.a1b2c3d4e5f6/`)
- *
- * This class builds an in-memory index by scanning filenames recursively, providing O(1) lookups
- * in both directions (ID→path and path→ID).
- *
- * The index is built lazily on first access to optimize Lambda cold starts.
- *
- * ## Multi-Process Consistency
- *
- * This class is NOT thread-safe. In multi-process environments (e.g., multiple Lambda
- * instances or server processes), each process maintains its own in-memory index.
- *
- * **Consistency guarantees:**
- * - Filenames on the filesystem are the source of truth
- * - Each process discovers the same filenames when building its index
- * - Write operations that change filenames are atomic (rename is atomic)
- * - Read operations always reflect current filesystem state after index rebuild
- *
- * **How staleness is bounded:**
- * - Same process: mutation sites invalidate registered ContentStores directly
- *   (content-index-registry.ts); the next access rebuilds.
- * - Other processes: mutation sites bump an on-disk generation marker
- *   (content-index-generation.ts) that ContentStore probes on access, so
- *   stale indexes converge within the probe interval plus NFS caching delay.
- * - Residual windows self-heal via ContentStore's suspicious-lookup rebuild
- *   (ID miss or index hit whose file is gone).
- *
- * **Race condition handling:**
- * - Multiple processes creating entries simultaneously: each generates a unique ID,
- *   so this cannot itself manufacture a duplicate-ID pair.
- * - ContentStore.write() refuses to recreate an entry file whose ID the
- *   directory listing places at a different slug (existence guard), so stale
- *   indexes cannot manufacture duplicate-ID files either. Together these two
- *   guarantees mean buildFromFilenames() can only ever encounter a duplicate
- *   ID that ALREADY existed on disk before the scan started (see below).
- *
- * ## Duplicate-ID quarantine (not fail-fast)
- *
- * A duplicate embedded ID can still land on disk from an external crash --
- * e.g. ContentStore.renameEntry()'s `fs.link()` then `fs.unlink()` is not
- * atomic, and a crash between the two steps leaves two filenames sharing one
- * ID. Earlier versions of this class threw on the first such collision,
- * which propagated out of every caller and (since ContentStore's rebuild has
- * no catch around it) permanently bricked read-by-id, reference resolution,
- * collection listing, and every write on the branch -- one bad pair took the
- * whole branch down.
- *
- * `buildFromFilenames()` now quarantines a collision instead of throwing:
- * the two (or more) candidates sharing an ID are resolved to a single
- * deterministic winner -- the lexicographically-**smallest** relativePath,
- * chosen purely by comparing the candidate strings, never by which one the
- * scan happened to visit first. This is what makes the choice agree across
- * hosts: two Lambdas (or a Lambda and the EC2 worker) scanning the same
- * directory can observe entries in different `readdir()` orders, but the
- * MIN of a fixed set of strings does not depend on visitation order, so
- * every host converges on the same winner. The loser(s) are excluded from
- * `idToLocation`/`pathToId`/`byCollection` entirely (as if not indexed) and
- * recorded in {@link getDuplicateIds} for admin-facing health reporting
- * (branch-health.ts) and repair (api/admin-branch-health.ts). A branch with a
- * quarantined duplicate is degraded (that one ID pair is invisible to
- * ID-based lookups) but not dead.
- *
- * ### What quarantine does NOT promise
- *
- * Quarantining is an INDEX decision: this scan never touches the filesystem,
- * so nothing here moves or deletes the dropped file. It does not follow that
- * the dropped file is inert until an admin repairs it, and an earlier version
- * of this comment wrongly claimed exactly that ("left untouched on disk until
- * a human or the repair action moves them"). Slugs are resolved by directory
- * scan (`ContentStore.buildPaths()`), which knows nothing about this
- * quarantine, so the dropped file stays fully addressable by
- * collection+slug: a stale editor tab can still save, delete or rename it.
- *
- * The dangerous case was the save. `ContentStore.write()`'s index-repair step
- * reads "the index says this ID lives somewhere else" as "the slug changed"
- * and unlinks that other file -- which, with a duplicate, is a DIFFERENT
- * document (the kept one). It silently deleted the winner while reporting
- * success. `write()` now refuses such a save with `DuplicateContentIdError`
- * instead (see its "[F1] duplicate-ID guard"). `delete()`/`renameEntry()`
- * were never affected: they only ever touch the file the caller addressed,
- * and are deliberately still allowed, so removing or moving the dropped file
- * by hand remains possible without an admin.
+ * Bidirectional ContentId <-> path index over `{type}.{slug}.{12-char-id}.{ext}`
+ * files and `{slug}.{12-char-id}/` directories, scanned lazily on first access
+ * into per-process memory. Filenames on disk are the source of truth; the class
+ * is not thread-safe and takes no locks. Staleness is bounded as the module
+ * header describes, plus ContentStore's suspicious-lookup rebuild.
+ *
+ * A duplicate embedded ID always predates the scan: concurrent creates each
+ * generate a unique ID, and ContentStore.write() refuses to recreate an entry
+ * file whose ID the directory listing places at a different slug. A crash does
+ * produce one — renameEntry()'s `fs.link()` then `fs.unlink()` is not atomic.
+ *
+ * `buildFromFilenames()` quarantines such a collision rather than throwing,
+ * which would propagate out of every caller and brick read-by-id, reference
+ * resolution, listing and every write on the branch. The winner is the
+ * lexicographically-SMALLEST relativePath, compared as strings and never by
+ * visit order, so hosts scanning in different `readdir()` orders converge on
+ * the same one. Losers leave `idToLocation`/`pathToId`/`byCollection` entirely
+ * and are recorded in {@link getDuplicateIds} for branch-health.ts and the
+ * repair action in api/admin-branch-health.ts: degraded, not dead.
+ *
+ * Quarantine is an INDEX decision only: this scan never touches the filesystem,
+ * and slugs resolve by directory scan (`ContentStore.buildPaths()`), which
+ * knows nothing about it, so the dropped file stays addressable by
+ * collection+slug. Hence `write()` refuses such a save with
+ * `DuplicateContentIdError` — its index-repair step reads "this ID lives
+ * elsewhere" as "the slug changed" and would unlink the kept file, a different
+ * document. `delete()`/`renameEntry()` stay allowed, each touching only the
+ * file the caller addressed, so the dropped file can be removed by hand.
  */
 export declare class ContentIdIndex {
     private idToLocation;
     private pathToId;
     private byCollection;
     /**
-     * IDs discovered on more than one file during buildFromFilenames, keyed by
-     * id, mapping to every quarantined (losing) path seen for that id. Never
-     * populated by add()/remove()/updatePath(), which still throw on collision
-     * -- see those methods' doc comments.
+     * Quarantined (losing) paths per duplicated id, populated by
+     * buildFromFilenames only: add()/remove()/updatePath() throw on collision.
      */
     private duplicateIds;
     private root;
     constructor(root: string);
     /**
-     * Build index by scanning filenames recursively. Duplicate embedded IDs
-     * are quarantined, not thrown on -- see the class doc comment's
-     * "Duplicate-ID quarantine" section and {@link getDuplicateIds}.
+     * Build the index by scanning filenames recursively. Duplicate embedded IDs
+     * are quarantined, not thrown on — see the class doc and
+     * {@link getDuplicateIds}.
      */
     buildFromFilenames(startPath?: string): Promise<void>;
     /** Insert a location into all three indexes. Caller must ensure no existing entry for this id. */
     private insertLocation;
-    /** Remove a location from all three indexes -- used when a lexicographically-earlier duplicate displaces it. */
+    /** Remove a location from all three indexes, when an earlier duplicate displaces it. */
     private evictLocation;
-    /** Record a quarantined duplicate path for admin-facing health reporting (see getDuplicateIds). */
+    /** Record a quarantined duplicate path for health reporting (see getDuplicateIds). */
     private recordDuplicate;
     private scanDirectory;
     /**
-     * IDs discovered on more than one file during the last buildFromFilenames
-     * scan. Empty unless the content tree currently has a duplicate-ID pair
-     * (see the class doc comment). Consumed by branch-health.ts's admin scan
-     * and by the repair-content-duplicates admin action
-     * (api/admin-branch-health.ts).
+     * IDs the last buildFromFilenames scan found on more than one file; empty
+     * otherwise. Consumed by branch-health.ts's admin scan and by the
+     * repair-content-duplicates action (api/admin-branch-health.ts).
      */
     getDuplicateIds(): DuplicateContentId[];
     /**
-     * The quarantine record for ONE id, or null when that id is not
-     * duplicated. The O(1) counterpart to {@link getDuplicateIds} for the
-     * write path, which has to ask this question on every save whose resolved
-     * path disagrees with the index (ContentStore.write()'s duplicate-ID
-     * guard) and must not pay for materializing the whole list.
+     * The quarantine record for ONE id, or null when that id is not duplicated.
+     * The O(1) counterpart to {@link getDuplicateIds}, for ContentStore.write()'s
+     * duplicate-ID guard: it asks on every save whose resolved path disagrees
+     * with the index, so it must not pay to materialize the whole list.
      */
     getDuplicateFor(id: string): DuplicateContentId | null;
-    /**
-     * Forward lookup: ID → location (O(1))
-     */
+    /** Forward lookup: ID → location (O(1)). */
     findById(id: string): IdLocation | null;
-    /**
-     * Reverse lookup: path → ID (O(1))
-     */
+    /** Reverse lookup: path → ID (O(1)). */
     findByPath(relativePath: PhysicalPath): ContentId | null;
-    /**
-     * Get all ID locations in the index.
-     * Useful for validation and checking references.
-     */
+    /** Every ID location in the index, for validation and reference checking. */
     getAllLocations(): IdLocation[];
-    /**
-     * Get all entries in a collection by collection path.
-     *
-     * Performance: O(1) + O(m) where m is the number of entries in the collection.
-     *
-     * @param collectionPath - The collection path (e.g., "content/posts")
-     * @returns Array of IdLocation objects for entries in the collection
-     */
+    /** Entries in one collection: O(1) + O(entries in it). */
     getEntriesInCollection(collectionPath: LogicalPath): IdLocation[];
     /**
-     * Get all entries in a collection and its subcollections (tree traversal).
-     * For example, getEntriesInCollectionTree("content/data-catalog") returns entries
-     * in "content/data-catalog", "content/data-catalog/openstax", etc.
-     *
-     * Performance: O(k * m) where k is number of matching collections and m is avg entries per collection.
-     *
-     * @param collectionPath - The root collection path to search
-     * @returns Array of IdLocation objects for entries in the collection tree
+     * Entries in a collection and every subcollection: "content/docs" returns
+     * "content/docs", "content/docs/api", and so on. O(matching collections ×
+     * entries each).
      */
     getEntriesInCollectionTree(collectionPath: LogicalPath): IdLocation[];
     /**
@@ -188,82 +105,53 @@ export declare class ContentIdIndex {
      *
      * Performance: O(n) where n is total number of entries.
      *
-     * @returns Array of all IdLocation objects that are entries
      */
     getAllEntryLocations(): IdLocation[];
     /**
-     * Add a new entry or collection to the index.
-     * Note: This only updates the in-memory index. The file with embedded ID
-     * must already exist on disk (created by ContentStore).
+     * Add an entry or collection. In-memory only: the file with the embedded ID
+     * must already exist on disk, created by ContentStore. Throws on collision.
      */
     add(location: Omit<IdLocation, 'id'>): void;
     /**
-     * Remove an entry or collection from the index by ID.
-     * Note: This only updates the in-memory index. The file must be deleted separately.
+     * Remove an entry or collection by ID. In-memory only: the caller deletes the
+     * file separately.
      */
     remove(id: ContentId): void;
     /**
-     * Update the path for an existing ID (e.g., after file rename/move).
-     * This is used to keep the index in sync when files are renamed.
+     * Repoint an existing ID at a new path; keeps the index in step with a
+     * rename or move. Throws when the ID is unknown.
      */
     updatePath(id: ContentId, newRelativePath: PhysicalPath): void;
 }
 /**
- * Extract ID from filename.
- * Returns null if filename doesn't contain an ID or is a metadata file.
+ * The ID embedded in a filename, or null when there is none.
  *
- * Pattern:
- * - Collection entry files: type.slug.id.ext → ID is parts[parts.length - 2] (e.g., "post.dune.a1b2c3d4e5f6.json")
- * - Collection directories: slug.id → ID is parts[1] (e.g., "posts.a1b2c3d4e5f6")
- * - Metadata files: .collection.json, .gitignore, etc. → null
- *
- * Edge cases:
- * - Slugs with dots: "post.my.page.a1b2c3d4e5f6.json" → extracts "a1b2c3d4e5f6"
- * - Hidden files with IDs: ".hidden.a1b2c3d4e5f6.json" → returns null (metadata)
- * - No ID present: "file.json" → returns null
+ * - entry file `type.slug.id.ext` → the second-to-last part; a dotted slug
+ *   ("post.my.page.a1b2c3d4e5f6.json") still resolves, since only position
+ *   from the end matters
+ * - collection directory `slug.id` → the last part
+ * - anything dot-prefixed → null, metadata, even `.hidden.a1b2c3d4e5f6.json`
  */
 export declare function extractIdFromFilename(filename: string): ContentId | null;
 /**
- * Resolve a logical collection path to its actual filesystem path with embedded IDs.
- * Recursively resolves each path segment to handle nested collections.
- *
- * Example:
- *   Input: resolveCollectionPath(root, "content/docs/api")
- *   Output: "/abs/path/to/content/docs.bChqT78gcaLd/api.meiuwxTSo7UN"
- *
- * @param root - Absolute path to the workspace root
- * @param logicalPath - Logical path from schema (e.g., "content/docs/api")
- * @returns Absolute filesystem path with embedded IDs, or null if path doesn't exist
+ * Resolve a logical collection path to the filesystem path with embedded IDs,
+ * one segment at a time so nested collections work: "content/docs/api" →
+ * "<root>/content/docs.bChqT78gcaLd/api.meiuwxTSo7UN". Null if it is not there.
  */
 export declare function resolveCollectionPath(root: string, logicalPath: LogicalPath): Promise<string | null>;
 /**
- * Extract entry type name from filename.
- * For collection entry files with pattern type.slug.id.ext, returns the type (first part).
- *
- * Examples:
- * - "post.my-slug.a1b2c3d4e5f6.json" → "post"
- * - "article.test.a1b2c3d4e5f6.md" → "article"
- * - "posts.a1b2c3d4e5f6" → null (directory, not an entry file)
- *
- * @param filename - The filename to parse
- * @returns Entry type name or null if not a valid entry file
+ * The entry type of an entry file: the first part of `type.slug.id.ext`, so
+ * "post.my-slug.a1b2c3d4e5f6.json" → "post". Null for anything else, including
+ * a collection directory ("posts.a1b2c3d4e5f6").
  */
 export declare function extractEntryTypeFromFilename(filename: string): string | null;
 /**
- * Extract slug from filename.
- *
- * Collection entries: type.slug.id.ext → slug is parts[1...-2] (between type and ID)
- * Directories: slug.id → slug is parts[0] (before ID)
- *
- * For collection entry files (4+ parts), automatically strips the first part (type) to extract just the slug.
- *
- * Examples:
- * - "post.my-slug.a1b2c3d4e5f6.json" → "my-slug" (4 parts)
- * - "post.my.page.a1b2c3d4e5f6.json" → "my.page" (dotted slug, 5 parts)
- * - "posts.a1b2c3d4e5f6" → "posts" (directory, 2 parts)
+ * The slug in a filename, lowercased: everything between the type and the ID in
+ * `type.slug.id.ext`, or the part before the ID in a `slug.id` directory. A
+ * dotted slug survives ("post.my.page.a1b2c3d4e5f6.json" → "my.page"). Falls
+ * back to the extensionless filename when there is no ID.
  *
- * @param filename - The filename to parse
- * @param entryTypeName - Optional entry type name for explicit type matching (e.g., "post")
- *                        If provided and matches first part, strips it from slug
+ * `entryTypeName`, when it matches the first part, strips that part explicitly
+ * instead of relying on the 4-part auto-detection.
  */
 export declare function extractSlugFromFilename(filename: string, entryTypeName?: string): Slug;