@software-dlc/cli 0.157.2

package/dist/local/workspace-claim-status.d.ts

@@ -0,0 +1,172 @@
+import type { PortableGraph } from '@software-dlc/graph/types';
+import type { LocalPendingClaim } from './workspace-built-content.js';
+/**
+ * `sdlc workspace status`: each node's claim status in a view
+ * (docs/specs/graph-claim-status.md, Statuses and Reading status).
+ *
+ *   unrecorded   no source reference says where its code is
+ *   planned      a pending claim merged under the `plan` gate
+ *   designed     a pending claim merged under the `design` gate
+ *   implemented  it has a source reference; `environment` is the furthest
+ *                one, in the order given, whose Git ref holds every commit
+ *                its references were recorded at
+ *   released     that environment is the last one given
+ *
+ * A node that cites no code (no source reference, and a type not in
+ * `cites_code`) follows the nodes that realize it: it takes the lowest status
+ * among them and names the ones that hold it back. A reference that no longer
+ * matches the code marks the node stale and leaves its status alone. The
+ * status is derived and never stored. Graph only, read only: Git is the
+ * caller's, through `ClaimStatusGit`.
+ */
+export declare const CLAIM_STATUSES: readonly ["unrecorded", "planned", "designed", "implemented", "released"];
+export type ClaimStatus = (typeof CLAIM_STATUSES)[number];
+export declare const CLAIM_STATUS_VIEWS: readonly ["planned", "built", "released"];
+export type ClaimStatusView = (typeof CLAIM_STATUS_VIEWS)[number];
+export type ClaimStatusEnvironment = {
+    key: string;
+    ref: string;
+};
+/** The Git reads the status takes, so callers and tests choose how. */
+export type ClaimStatusGit = {
+    /** The full commit a ref names, or null when the repository lacks it. */
+    resolve(ref: string): Promise<string | null>;
+    /** Whether `ref` contains `commit`; false when either is unknown. */
+    isAncestor(commit: string, ref: string): Promise<boolean>;
+    /** A file's lines at a commit, split on newlines only, or null when absent. */
+    lines(commit: string, path: string): Promise<string[] | null>;
+};
+export type ClaimReference = {
+    path: string;
+    symbol: string | null;
+    lines: [number, number] | null;
+    commit: string | null;
+    relations: string[];
+    legacy: boolean;
+};
+export type ClaimStale = {
+    path: string;
+    status: string;
+    detail: string;
+};
+export type ClaimHeldBack = {
+    node: string;
+    type: string | null;
+    label: string | null;
+};
+export type ClaimEstablishedBy = {
+    references: number;
+    commits: string[];
+    ref?: string;
+} | {
+    gate: 'planned' | 'designed';
+    gate_commits: string[];
+    work_streams: string[];
+} | {
+    realized_by: number;
+    held_back: number;
+    held_back_by: ClaimHeldBack[];
+};
+export type ClaimStatusEntry = {
+    status: ClaimStatus;
+    environment: string | null;
+    established_by: ClaimEstablishedBy | null;
+    stale: ClaimStale[];
+};
+/** A reference pinned to a claim version the node has since moved past. */
+export type ClaimBehind = {
+    reference_id: string;
+    provider_key: string;
+    resource: string;
+    claim_object_hash: string;
+};
+export type ClaimStatusNode = ClaimStatusEntry & {
+    node: string;
+    type: string | null;
+    label: string | null;
+    /** It cites no code and takes its status from the nodes that realize it. */
+    follows: boolean;
+    /**
+     * Its accepted references whose claim_object_hash differs from its current
+     * object hash (docs/specs/evidence-claim-freshness.md): a mark, like stale,
+     * that leaves the status alone.
+     */
+    behind: ClaimBehind[];
+    /** In the planned view, for a node with a pending claim: what it is built as; null when never built. */
+    built_as?: {
+        status: ClaimStatus;
+        environment: string | null;
+    } | null;
+};
+type Counts = Record<ClaimStatus, number>;
+export type ClaimStatusResult = {
+    version: 1;
+    view: ClaimStatusView;
+    workspace_id: string;
+    /** The graph commit read. */
+    graph_commit_id: string;
+    /** The code the references were checked against. */
+    commit: string;
+    environments: Array<ClaimStatusEnvironment & {
+        resolved: boolean;
+    }>;
+    cites_code: string[];
+    pending: {
+        nodes: number;
+        marked_for_removal: string[];
+        other_claims: Record<string, number>;
+    };
+    nodes: number;
+    by_status: Counts;
+    implemented_by_environment: Record<string, number>;
+    stale_nodes: number;
+    /** Nodes with any reference behind its claim. */
+    behind_nodes: number;
+    following: {
+        nodes: number;
+        by_status: Counts;
+        unrealized: number;
+    };
+    by_type: Record<string, Counts>;
+    other_claims: {
+        edges: number;
+        paths: number;
+        path_relations: number;
+    };
+    /** Present only when the read names nodes or a status, so an unasked read stays bounded. */
+    claims?: ClaimStatusNode[];
+    /** Named nodes absent from this view: not in the graph, never built, or not released. */
+    not_found?: string[];
+};
+export declare function parseClaimStatusView(value: string | null | undefined): ClaimStatusView;
+export declare function parseClaimStatus(value: string): ClaimStatus;
+/** `<key>=<ref>`, in promotion order. */
+export declare function parseClaimStatusEnvironment(value: string): ClaimStatusEnvironment;
+/** A node's source references; a legacy location gives only its path. */
+export declare function claimReferences(node: unknown): ClaimReference[];
+/** How a symbol stands in a file's lines: ok, symbol_missing, symbol_undefined, or symbol_moved (outside `span`). */
+export declare function symbolStatus(symbol: string, lines: string[], span: [number, number] | null, defines: boolean, path: string): string;
+/** (status, detail) of one reference at `commit`; anything but ok and legacy is stale. */
+export declare function referenceStatus(git: ClaimStatusGit, commit: string, reference: ClaimReference, lines_at?: (commit: string, path: string) => Promise<string[] | null>): Promise<[string, string | null]>;
+/** {node: the nodes that realize it, sorted} for every node whose type REALIZED_BY lists. */
+export declare function claimRealizers(graph: PortableGraph): Map<string, string[]>;
+/** Every node's status at `commit`, with the counts; the node list only when asked for. */
+export declare function claimStatus(input: {
+    graph: PortableGraph;
+    pending: LocalPendingClaim[];
+    workspace_id: string;
+    graph_commit_id: string;
+    git: ClaimStatusGit;
+    commit: string;
+    environments: ClaimStatusEnvironment[];
+    cites_code: string[];
+    view?: ClaimStatusView;
+    nodes?: string[];
+    status?: ClaimStatus;
+    stale_only?: boolean;
+    behind_only?: boolean;
+}): Promise<ClaimStatusResult>;
+/** The Git reads of the repository holding `cwd`, through the git command. */
+export declare function gitClaimStatusReader(cwd: string): ClaimStatusGit;
+export {};
+//# sourceMappingURL=workspace-claim-status.d.ts.map

package/dist/local/workspace-claim-status.d.ts.map

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