@poetics/cli 0.1.2 → 0.2.0

package/dist/backfill.d.ts

@@ -0,0 +1,98 @@
+import type { Inferred, Unit, Version } from "@poetics/core";
+import type { PoeticsConfig, StoreLayout } from "@poetics/store";
+/** One piece of evidence about why a unit exists. */
+export interface Evidence {
+    source: Inferred["sources"][number];
+    /** Where it came from: a commit, a file, a path. */
+    ref: string;
+    text?: string;
+}
+export interface BackfillPlan {
+    /** New units, each with its inferred rationale, ready to write. */
+    created: Array<{
+        unit: Unit;
+        evidence: Evidence[];
+    }>;
+    byConfidence: Record<Inferred["confidence"], number>;
+    /** Existing units with code changes nobody recorded: `poetics index` is the tool for those. */
+    unrecorded: number;
+    /** Existing units the code has TSDoc or a sibling test for that the unit file lacks. */
+    missingDocs: Array<{
+        uid: string;
+        name: string;
+        file: string;
+    }>;
+    missingTests: Array<{
+        uid: string;
+        name: string;
+        file: string;
+        test: string;
+    }>;
+    /** Comments that read like a workaround or an invariant: candidates for a note, never written. */
+    candidateNotes: Array<{
+        file: string;
+        line: number;
+        text: string;
+    }>;
+}
+/** What a snapshot backfill would write. Nothing is written until `applyBackfill`. */
+export declare function planBackfill(root: string, config: PoeticsConfig): Promise<BackfillPlan>;
+/** Writes the planned units, each as the actor its evidence names. Returns how many were written. */
+export declare function applyBackfill(root: string, plan: BackfillPlan, layout?: StoreLayout): Promise<number>;
+/** The report for people: confidence counts, then what to add or record by hand. */
+export declare function formatBackfillPlan(plan: BackfillPlan, written?: number): string;
+/** Whether there is anything to write. */
+export declare function hasBackfill(plan: BackfillPlan): boolean;
+/** A unit's reconstructed history, or why it stops short. */
+export interface PrehistoryEntry {
+    uid: string;
+    name: string;
+    file: string;
+    prehistory: Version[];
+    /** Where matching would only queue the unit: its history before this commit is not claimed. */
+    stoppedAt?: {
+        commit: string;
+        reason: string;
+    };
+}
+export interface PrehistoryPlan {
+    /** First-parent commits walked, oldest first. */
+    commits: number;
+    /** The range walked, as full commit ids: after `from` (the root when unset) up to and including `to`. */
+    range: {
+        from?: string;
+        to: string;
+    };
+    units: PrehistoryEntry[];
+    /** Units first recorded after `to`: left for a walk that reaches them, since prehistory can only be extended further back. */
+    beyond: number;
+    /** With `includeRemoved`: exports deleted before anyone recorded them, as new unit files ending in `removed`. */
+    removed: Unit[];
+}
+/** Where `poetics backfill --history [from] [to]` walks (refs or commit ids, both optional), and whether to recover deleted exports. */
+export interface PrehistoryRange {
+    from?: string;
+    to?: string;
+    /** `--include-removed`: recover exports deleted before they were recorded (ADR 0011). */
+    includeRemoved?: boolean;
+}
+/**
+ * `poetics backfill --history` (ADR 0011): walks the first-parent history,
+ * reads each changed file's units syntactically, and follows them from commit
+ * to commit with `matchIdentities`, recording a version whenever a unit's code
+ * changed. A unit's prehistory is what happened before the commit that first
+ * recorded its unit file. Where matching would only queue a unit, its history
+ * restarts there, and the plan says so: history is never guessed.
+ *
+ * `range` limits the walk to the first-parent commits after `from` up to `to`
+ * (default: the root to HEAD). Code that exists at `from` starts there: its
+ * first change in the range opens its prehistory, which a later walk from
+ * further back extends. Units first recorded after `to` are left out, since
+ * prehistory that stops short of their recording could never be filled in.
+ */
+export declare function planPrehistory(root: string, config: PoeticsConfig, range?: PrehistoryRange): Promise<PrehistoryPlan>;
+/** Writes each unit's prehistory, unless it already has exactly that, and a unit file for each recovered deletion. Returns how many unit files changed. */
+export declare function applyPrehistory(root: string, plan: PrehistoryPlan, layout?: StoreLayout): Promise<number>;
+/** The prehistory plan for people: one line per unit with how far back it reaches, then a summary. */
+export declare function formatPrehistoryPlan(plan: PrehistoryPlan, written?: number): string;
+//# sourceMappingURL=backfill.d.ts.map

package/dist/backfill.d.ts.map

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