@davidorex/pi-context 0.26.0

package/dist/context-dir.js.map

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

package/dist/context-sdk.d.ts

@@ -0,0 +1,428 @@
+/**
+ * Project SDK — queryable surface for project block state, discovery,
+ * and derived metrics. Computes everything dynamically from filesystem
+ * and git — no cache, no stale data.
+ */
+import { type ConfigBlock } from "./context.js";
+export { type BlockKindDecl, type CompositionMember, type ConfigBlock, type ContextData, type CurationSuggestion, displayName, type Edge, edgesForLens, groupByLens, type HierarchyDecl, type InvariantDecl, type ItemRecord, type LayerDecl, type LensSpec, listUncategorized, loadConfig, loadContext, loadRelations, type RelationTypeDecl, type StatusBucket, type SubstrateValidationIssue, type SubstrateValidationResult, synthesizeFromField, validateRelations, walkDescendants, } from "./context.js";
+export interface BlockInfo {
+    name: string;
+    hasSchema: boolean;
+}
+export declare function availableBlocks(cwd: string): BlockInfo[];
+/**
+ * Discover schemas in the substrate dir's `schemas/` subdirectory (resolved
+ * via `schemasDir(cwd)` per DEC-0015). Returns sorted list of
+ * absolute paths to .schema.json files.
+ */
+export declare function availableSchemas(cwd: string): string[];
+/**
+ * Discover blocks with array properties by scanning the substrate dir's
+ * `schemas/` subdirectory (resolved via `schemasDir(cwd)` per
+ * DEC-0015) for schemas whose root type has at least one array property.
+ * Returns block name, first array key, and schema path for each.
+ */
+export declare function findAppendableBlocks(cwd: string): Array<{
+    block: string;
+    arrayKey: string;
+    schemaPath: string;
+}>;
+/** Default planning lifecycle block types shipped with /context init. */
+export declare const CONTEXT_BLOCK_TYPES: readonly ["project", "domain", "requirements", "architecture", "tasks", "decisions", "issues", "rationale", "verification", "handoff", "conformance-reference", "audit"];
+export interface SchemaProperty {
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+    enum?: string[];
+}
+export interface SchemaInfo {
+    name: string;
+    title: string;
+    properties: SchemaProperty[];
+    arrayKeys: string[];
+    itemProperties?: Record<string, SchemaProperty[]>;
+}
+/**
+ * Read and parse a schema, extracting property metadata.
+ * Returns null if the schema file doesn't exist or is unparseable.
+ */
+export declare function schemaInfo(cwd: string, schemaName: string): SchemaInfo | null;
+/**
+ * Extract schema property metadata from an ABSOLUTE schema file path.
+ * Identical extraction to `schemaInfo` but addressed by path rather than
+ * (cwd, name) — lets package-intrinsic consumers (e.g. samples-catalog) read
+ * the extension's bundled samples/schemas/*.schema.json without a project
+ * substrate. Returns null if the schema file doesn't exist or is unparseable.
+ */
+export declare function schemaInfoFromPath(absSchemaPath: string, schemaName: string): SchemaInfo | null;
+/**
+ * All schemas with their property metadata.
+ * Scans the substrate dir's `schemas/` subdirectory (resolved via
+ * `schemasDir(cwd)` per DEC-0015) and parses each schema.
+ */
+export declare function schemaVocabulary(cwd: string): SchemaInfo[];
+export interface BlockStructure {
+    name: string;
+    exists: boolean;
+    hasSchema: boolean;
+    arrays: {
+        key: string;
+        itemCount: number;
+    }[];
+}
+/**
+ * What blocks exist and their structure — combines availableBlocks
+ * and block summaries into a single queryable function.
+ */
+export declare function blockStructure(cwd: string): BlockStructure[];
+export interface ArraySummary {
+    total: number;
+    byStatus?: Record<string, number>;
+}
+export interface BlockSummary {
+    arrays: Record<string, ArraySummary>;
+}
+/**
+ * Zero-loss derived "where are we + what's next" state (DEC-0040 / FGAP-072 /
+ * FGAP-059). A pure function of `.project` substrate — focus, in-flight units,
+ * atomic-next ranked actions, and blocked tasks are all DERIVED, never
+ * hand-stored. Built to serve `.context` identically once that substrate-dir
+ * lands. Reuses existing primitives (buildIdIndex / loadRelations / topoSort);
+ * introduces no new traversal or status logic.
+ */
+export interface CurrentState {
+    /** one-line: active in-flight ids, else current in-progress phase, else "no active focus." */
+    focus: string;
+    /** tasks with status "in-progress" */
+    inFlight: {
+        id: string;
+        block: string;
+        description: string;
+    }[];
+    /** atomic-next, ranked: open framework-gaps (by priority) then unblocked planned tasks (topo order) */
+    nextActions: {
+        id: string;
+        kind: string;
+        priority?: string;
+        reason: string;
+    }[];
+    /** planned tasks whose task_depends_on_task dependency parents are not ALL completed */
+    blocked: {
+        id: string;
+        block: string;
+        blockedBy: string[];
+    }[];
+}
+/**
+ * The four-state bootstrap progression, derived purely from the filesystem
+ * (DEC-0040 — nothing stored). Consumed by the `/context start` conductor, the
+ * dispatch READY-gate, and the startup-slot hint (DEC-0042 / FGAP-095).
+ */
+export type BootstrapState = "no-pointer" | "no-config" | "not-installed" | "ready";
+export interface BootstrapStatus {
+    /** which stop in the bootstrap progression `cwd` is at */
+    state: BootstrapState;
+    /** absolute substrate dir once the `.pi-context.json` pointer exists, else null */
+    contextDir: string | null;
+    /** declared-but-unmaterialized installed assets — populated only for "not-installed", else empty */
+    missing: {
+        schemas: string[];
+        blocks: string[];
+    };
+}
+/**
+ * Derive the bootstrap progression for `cwd` from the filesystem, in order:
+ *   no-pointer    — no `.pi-context.json` (checked directly so this NEVER throws
+ *                   pre-bootstrap — it is the unset-substrate detection read the
+ *                   harness-confined LLM uses to redirect the human to `/context start`)
+ *   no-config     — pointer present, no `config.json`
+ *   not-installed — config present, some declared installed_* asset is absent
+ *   ready         — config present, all declared assets materialized (or none declared)
+ *
+ * Does NOT swallow corruption: a malformed `config.json` propagates
+ * `loadConfig`'s ValidationError — the four states are the NORMAL progression;
+ * corruption is a separate error condition, not a bootstrap stop.
+ */
+export declare function deriveBootstrapState(cwd: string): BootstrapStatus;
+export interface ContextState {
+    testCount: number;
+    sourceFiles: number;
+    sourceLines: number;
+    lastCommit: string;
+    lastCommitMessage: string;
+    recentCommits: string[];
+    blockSummaries: Record<string, BlockSummary>;
+    phases: {
+        total: number;
+        current: number;
+    };
+    blocks: number;
+    schemas: number;
+    requirements?: {
+        total: number;
+        byStatus: Record<string, number>;
+        byPriority: Record<string, number>;
+    };
+    tasks?: {
+        total: number;
+        byStatus: Record<string, number>;
+    };
+    domain?: {
+        total: number;
+    };
+    verifications?: {
+        total: number;
+        passed: number;
+        failed: number;
+    };
+    hasHandoff?: boolean;
+}
+/**
+ * Derive project state from authoritative sources at query time.
+ * No cache, no stale data — computed fresh on every call.
+ */
+export declare function contextState(cwd: string): ContextState;
+/**
+ * Derive {@link CurrentState} ("where are we + what's next") purely from
+ * `.project` substrate. No writes; tolerant of absent optional blocks (every
+ * branch defaults to empty rather than throwing).
+ *
+ * Edge-direction contract for blocked/ready derivation (verified against
+ * roadmap-plan.ts:471 — the topoSort-deps mapping for phase_depends_on uses the
+ * identical convention): a `task_depends_on_task` edge `{parent: D, child: T}`
+ * means task T DEPENDS ON task D, so D must reach status "completed" before T is
+ * unblocked. (relation name source_verb_target = task_depends_on_task ⇒ child is
+ * the source/dependent, parent is the target/prerequisite; config display_name
+ * "depends on task".)
+ */
+export declare function currentState(cwd: string): CurrentState;
+/**
+ * Predicate operators for filterBlockItems. Each operator carries a
+ * documented semantic against `item[field]`:
+ *   - `eq`      : strict-equality (===) against `value`
+ *   - `neq`     : strict-inequality (!==) against `value`
+ *   - `in`      : `value` must be an array; matches when item[field] is in it
+ *   - `matches` : item[field] must be a string; tested against `new RegExp(value)`
+ *
+ * The match policy for items missing the predicate field is uniform:
+ * `item[field] === undefined` → NOT a match (returns false) for every
+ * operator. Rationale: returning early avoids throwing on heterogeneous
+ * block arrays where some items legitimately lack the field; callers that
+ * want a hard "field must exist" gate compose with `op: "neq", value: undefined`
+ * (still excluded by the undefined branch — current semantic is filter, not
+ * schema assertion). Documented here rather than via throw so callers get a
+ * cleanly-typed empty/partial array rather than a runtime trap.
+ */
+export interface FilterPredicate {
+    field: string;
+    op: "eq" | "neq" | "in" | "matches";
+    value: unknown;
+}
+/**
+ * Filter the array items of a block by a predicate. Reads the block via the
+ * canonical block-api `readBlock`, discovers the single top-level array key,
+ * and returns a new array of items satisfying the predicate. The source
+ * block is never mutated.
+ *
+ * Behavior contract:
+ *   - Block must exist; underlying `readBlock` throw propagates.
+ *   - Block must have exactly one top-level array property (single-array
+ *     assumption — same as inject-context-items.ts).
+ *   - Items missing the predicate field never match (see FilterPredicate
+ *     docstring for rationale).
+ *   - `op: "in"` requires `value` to be an array; otherwise no items match.
+ *   - `op: "matches"` constructs `new RegExp(String(value))`; a malformed
+ *     regex pattern throws synchronously from the RegExp constructor.
+ *
+ * Closes part of the FGAP-026 phase 2 query-surface gap (TASK-034).
+ */
+export declare function filterBlockItems(cwd: string, blockName: string, predicate: FilterPredicate): unknown[];
+export interface BlockPage {
+    items: unknown[];
+    total: number;
+    hasMore: boolean;
+}
+/**
+ * Read a single item from ONE named block by its id, or null if absent.
+ * Block-scoped (no cross-substrate idIndex, no prefix-vs-block invariant — that is resolveItemById).
+ * Reuses filterBlockItems(id eq) so it inherits readBlock + discoverArrayKey + edge semantics
+ * (missing block / multiple top-level arrays THROW; no-array block or id-not-found → null). FGAP-045.
+ */
+export declare function readBlockItem(cwd: string, blockName: string, id: string): unknown | null;
+/**
+ * Paginate a block's items. Reuses readBlock + discoverArrayKey. Returns the FULL count as `total`
+ * (not the page length) and `hasMore = offset + limit < total`. No-array block → {items:[],total:0,
+ * hasMore:false}; offset ≥ total → empty items with correct total. Missing block / multiple top-level
+ * arrays propagate the throw (consistent with filterBlockItems). FGAP-045.
+ */
+export declare function readBlockPage(cwd: string, blockName: string, opts?: {
+    offset?: number;
+    limit?: number;
+}): BlockPage;
+export interface JoinSpec {
+    leftBlock: string;
+    rightBlock: string;
+    relationType?: string;
+    leftField?: string;
+    rightField?: string;
+    leftEndpoint?: "parent" | "child";
+    leftPredicate?: FilterPredicate;
+}
+export interface JoinResult {
+    left: Record<string, unknown>;
+    right: Record<string, unknown>[];
+}
+/**
+ * Cross-block join (FGAP-043, HYBRID). Mode = exactly one of relationType (edge) XOR
+ * leftField+rightField (field). Returns one JoinResult per left item (after leftPredicate),
+ * right always an array. Edge mode is DEC-0013-native (relations.json); field mode joins on a
+ * shared field value (legacy inline-FK + arbitrary shared fields). Reuses filterBlockItems /
+ * readBlock / discoverArrayKey / loadRelations / buildIdIndex.
+ */
+export declare function joinBlocks(cwd: string, spec: JoinSpec): JoinResult[];
+/**
+ * Locator for a single item discovered by buildIdIndex: which block file it
+ * lives in, which array key inside that block holds it, and the item payload.
+ * Intended as the substrate for renderer-driven cross-reference resolution
+ * (e.g., a per-item macro inlining a related decision by ID).
+ */
+export interface ItemLocation {
+    block: string;
+    arrayKey: string;
+    item: Record<string, unknown>;
+}
+/**
+ * Look up the block expected to host an ID based on its prefix, driven by
+ * the config registry.
+ *
+ * Resolution: scan `cfg.block_kinds[]` for the longest-matching `prefix`
+ * and return its `canonical_id`. Returns null when:
+ *   - `cfg` is null (no config / pre-bootstrap project — graceful fallback)
+ *   - no `block_kinds[].prefix` matches the id (bare phase IDs, legacy
+ *     unprefixed IDs, future prefixes not yet registered)
+ *
+ * Registry is config-driven from line 1 — prefix conflicts surface at
+ * config-registration time rather than fixture-write time. Closes issue-089
+ * class (PLAN- vs PLAN-NNN collision) structurally.
+ *
+ * Longest-prefix wins so that compatible registrations like `R-` and
+ * `REVIEW-` resolve unambiguously.
+ */
+export declare function expectedBlockForId(id: string, cfg: ConfigBlock | null): string | null;
+/**
+ * Build a map from item-ID to its location across every block in `.project/`.
+ *
+ * Scan strategy:
+ *   - `.project/*.json` — every array property whose items are objects with
+ *     a string `id` field becomes an indexed entry. Phases participate as an
+ *     ordinary array-block since DEC-0028 (PHASE-NNN ids in `phase.json` under
+ *     the plural `phases` array key); there is no dedicated file-per-phase branch.
+ *
+ * Prefix invariant: when an item ID starts with one of the prefixes registered
+ * in `config.block_kinds[]`, the block it was found in must match that
+ * registry's `canonical_id`. Mismatches throw immediately — schema patterns
+ * make this state unreachable through validated writes, so encountering one
+ * indicates either a direct-fs corruption or an unmapped prefix collision that
+ * needs explicit resolution. When no config exists (pre-bootstrap project),
+ * the prefix invariant is silently skipped — every encountered id is indexed
+ * without enforcement.
+ *
+ * Collisions on identical IDs across different blocks: first writer wins
+ * (no overwrite) — duplicate entries are intentionally ignored to keep
+ * the resolver deterministic without allocating warning channels here.
+ */
+export declare function buildIdIndex(cwd: string): Map<string, ItemLocation>;
+/**
+ * One-off lookup — builds the full index then performs a single get.
+ * Callers performing multiple lookups in one render pass should call
+ * `buildIdIndex` once and reuse the returned map.
+ */
+export declare function resolveItemById(cwd: string, id: string): ItemLocation | null;
+/**
+ * Bulk variant of `resolveItemById` — resolve N ids against a single
+ * `buildIdIndex` traversal. Complements the singular form (which remains
+ * available for one-off renderer-driven lookups) by collapsing N independent
+ * `buildIdIndex` rebuilds into one. Coexists with the singular surface;
+ * neither supersedes the other.
+ *
+ * Semantics:
+ *   - Returns a `Map<string, ItemLocation | null>` whose entries are keyed
+ *     by the INPUT ids exactly as supplied (no normalization, no dedup
+ *     beyond Map's intrinsic key-uniqueness). Duplicate input ids therefore
+ *     collapse to one map entry — caller-side responsibility if multiplicity
+ *     matters; the canonical bulk-lookup contract is "set of ids → set of
+ *     resolutions" rather than "list → list".
+ *   - For each input id: present in the index → its `ItemLocation`; absent
+ *     → null entry. Every input id has an entry in the returned map (no
+ *     silent drops); this is the property that distinguishes the bulk
+ *     surface from a partial-result `getMany`.
+ *   - Empty input (`ids: []`) returns an empty Map (no index build cost
+ *     beyond the unavoidable directory existence check inside buildIdIndex).
+ *   - Insertion order matches the first-encounter order of `ids` (standard
+ *     ES Map semantics on `.set`).
+ *
+ * Behavior contract:
+ *   - Single `buildIdIndex(cwd)` invocation regardless of `ids.length`
+ *     (closes the N×singular-call pattern that motivated the bulk surface).
+ *   - Prefix-vs-block invariant violations inside the index build propagate
+ *     out as-is — same surface contract as `resolveItemById`.
+ *
+ * Closes part of the FGAP-026 phase 2 query-surface gap (TASK-035).
+ */
+export declare function resolveItemsByIds(cwd: string, ids: string[]): Map<string, ItemLocation | null>;
+export interface ContextValidationIssue {
+    severity: "error" | "warning";
+    message: string;
+    block: string;
+    /**
+     * Defect locator within the block. Required for cross-block reference
+     * diagnostics; optional for lens-validator-sourced issues whose
+     * locator (e.g. phase_id) does not always map to a field path.
+     */
+    field?: string;
+    /**
+     * Opaque diagnostic slug from a registered lens-validator
+     * (e.g. roadmap_lens_missing). Absent on issues produced by the
+     * built-in cross-block reference scan, which has no slug surface
+     * (its diagnostics are uniquely identified by block + field).
+     */
+    code?: string;
+}
+export interface ContextValidationResult {
+    status: "clean" | "warnings" | "invalid";
+    issues: ContextValidationIssue[];
+}
+/**
+ * Validate cross-block referential integrity against the EDGE model
+ * (DEC-0013: `relations.json` closure-table edges are THE reference surface).
+ * Returns structured issues rather than throwing.
+ *
+ * Edge integrity replaces the pre-DEC-0036 per-block inline-FK reference scan:
+ * each edge's `parent`/`child` must resolve to a known item id (via the unified
+ * `buildIdIndex`), and each edge's `relation_type` must be registered in
+ * `config.relation_types[]` (DEC-0030 tripartite canonical_ids). Cycle
+ * detection is delegated to `validateRelations` (its `edge_cycle_detected`
+ * diagnostics are merged in).
+ *
+ * Substrate invariants beyond edge integrity are enforced generically from
+ * `config.invariants[]` per the `requires-edge` class — no invariant vocabulary
+ * (block kind / status / relation_type / direction) lives in source (DEC-0025).
+ * The canonical pi-context conception declares two invariants as config DATA:
+ * `completed-task-has-verification` and `decision-cites-forcing-artifact`; a
+ * project ships only the invariants its own conception requires.
+ */
+export declare function validateContext(cwd: string): ContextValidationResult;
+export interface CompleteTaskResult {
+    taskId: string;
+    verificationId: string;
+    verificationStatus: string;
+    previousStatus: string;
+}
+/**
+ * Gate task completion on verification. Reads the verification block to confirm
+ * a passing verification entry exists targeting this task, then atomically
+ * updates the task status to "completed" with the verification cross-reference.
+ */
+export declare function completeTask(cwd: string, taskId: string, verificationId: string): CompleteTaskResult;
+//# sourceMappingURL=context-sdk.d.ts.map

package/dist/context-sdk.d.ts.map

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