jackherd 0.0.1 → 1.0.0

package/dist/plan-format.d.ts

@@ -0,0 +1,325 @@
+declare const PLAN_LANGUAGE: {
+    readonly de: "de";
+    readonly en: "en";
+};
+type PlanLanguage = (typeof PLAN_LANGUAGE)[keyof typeof PLAN_LANGUAGE];
+/** The language's name as a reply or a question says it. */
+declare const LANGUAGE_NAME: Record<PlanLanguage, string>;
+declare const isPlanLanguage: (value: string) => value is PlanLanguage;
+declare const PLAN_STATUS: {
+    readonly done: "done";
+    readonly abandoned: "abandoned";
+    readonly inProgress: "inProgress";
+    readonly draft: "draft";
+    readonly other: "other";
+    readonly none: "none";
+};
+type PlanStatus = (typeof PLAN_STATUS)[keyof typeof PLAN_STATUS];
+type StatusWord = {
+    label: string;
+    /** Lower-case words a `Status:` line starts with; empty for `other` and `none`. */
+    leading: readonly string[];
+    /** Lower-case fragments that classify a `Status:` line wherever they appear. */
+    anywhere: readonly string[];
+};
+type PlanVocabulary = {
+    header: {
+        date: string;
+        status: string;
+        scope: string;
+    };
+    sections: {
+        decisions: string;
+        implementation: string;
+        modelRecommendations: string;
+        dependencies: string;
+        documentation: string;
+        lanes: string;
+        goal: string;
+        history: string;
+        plans: string;
+    };
+    columns: {
+        dependsOn: string;
+        writes: string;
+        serialMarker: string;
+    };
+    phase: string;
+    /** Opens the line by which a phase says it has no review gate on purpose: `**Kein Review-Gate:** <reason>`. */
+    noReviewGate: string;
+    /** Marks a lane as closed when its name cell contains it. */
+    laneClosed: string;
+    /** Words that may stand between two phases of one entry (`P1 Rule und P2 Monitor`). */
+    phaseConnectors: readonly string[];
+    statusWords: Record<PlanStatus, StatusWord>;
+};
+declare const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary>;
+/** Classifies a free-text `Status:` line; the first matching status in precedence order wins. */
+declare const classifyStatus: (language: PlanLanguage, statusText: string) => PlanStatus;
+/** `### Phase 3: Title` as the plan spells it in `language`. */
+declare const phaseHeading: (language: PlanLanguage, id: string, title: string) => string;
+declare const sectionHeading: (language: PlanLanguage, section: keyof PlanVocabulary["sections"]) => string;
+
+type DriftFinding = {
+    file: string;
+    reason: string;
+};
+/**
+ * Plans whose own status text or closing documentation phase admits unfinished architecture work.
+ * Plans in flight are skipped: open items there are expected, not drift.
+ */
+declare const findDrift: (file: string, content: string, language: PlanLanguage) => DriftFinding[];
+
+type PlanHeader = {
+    title: string;
+    date: string;
+    status: string;
+    statusWord: PlanStatus;
+    scope: string;
+};
+declare const readPlanHeader: (markdown: string, language: PlanLanguage, fallbackTitle: string) => PlanHeader;
+/** Rows of the decision table, counted by their `D<number>` first cell. */
+declare const countDecisions: (markdown: string) => number;
+
+/**
+ * `namedPhaseIds` holds every id the row names when `withoutRepeats` dropped some because an earlier row of the lane
+ * named them; `withoutRow` marks a step no board row wrote: the phases a lane worked on without a row of their own.
+ */
+type PlanStep = {
+    planTitle: string;
+    planHref: string | null;
+    phaseIds: string[];
+    label: string;
+    startsAfter: string;
+    model: string;
+    namedPhaseIds?: string[];
+    withoutRow?: true;
+};
+/** A lane of the sprint table; `closed` when its name cell says the lane was cleaned up. */
+type SprintLane = {
+    name: string;
+    port: number | null;
+    steps: PlanStep[];
+    closed: boolean;
+};
+/** Sprint tables name a phase `P4`; the sidebar title prints it the same way. */
+declare const PHASE_ID_PREFIX = "P";
+/** The phase ids a phases cell of the lanes table names, read as `parseSprintLanes` reads them. */
+declare const phaseIdsOfCell: (cell: string, language: PlanLanguage) => string[];
+declare const laneNameOf: (cell: string, previous: string | null) => string | null;
+/** The step without the phases an earlier step of the lane already named from the same plan, which `namedPhaseIds` keeps. */
+declare const withoutRepeats: (lane: SprintLane, step: PlanStep) => PlanStep;
+/**
+ * The lanes of the sprint document's lanes table (`## Spuren` in `de`) in table order. A row whose
+ * first cell names a lane in backticks belongs to that lane; a `↳` row without a name continues
+ * the lane above it.
+ */
+declare const parseSprintLanes: (markdown: string, language: PlanLanguage) => SprintLane[];
+declare const sprintTitleOf: (markdown: string, fallback: string) => string;
+/** The repository path of a plan link, relative to the sprint document's directory. */
+declare const resolvePlanPath: (sprintDirectory: string, href: string) => string;
+
+/** Per heading that carries checkboxes or table status cells: how many are done and open. */
+type PhaseTally = {
+    title: string;
+    done: number;
+    open: number;
+    model: string | undefined;
+};
+/**
+ * Every level-2 or level-3 section whose heading starts with a number (optionally after the phase
+ * word) and that holds at least one checkbox or ✅/⬜ table cell, with the model its recommendation
+ * table names for that phase. An open checkbox moved on with `→ P<n>` counts as open in the section
+ * of phase `<n>` instead of its own; with no such section it stays open where it is, as in `parsePlanPhases`.
+ */
+declare const tallyPhases: (markdown: string, language: PlanLanguage) => PhaseTally[];
+
+/** A checkbox of a plan. `gate` is set on the ones listed under the phase's review gate, and only on those. */
+type ChecklistItem = {
+    done: boolean;
+    text: string;
+    gate?: true;
+};
+/** An open checkbox that ends in `→ P<n>`: moved on purpose to phase `target`, its text without the marker. */
+type DeferredItem = {
+    text: string;
+    target: string;
+};
+/** An open checkbox whose phase arrow is not at the end of its line (1-based), with the form the parser reads. */
+type MisplacedDeferral = {
+    line: number;
+    target: string;
+    corrected: string;
+};
+/**
+ * `touched` is set by the phase source when the worktree's ticks differ from the base branch's. `deferred` holds
+ * the checkboxes moved to another phase; they are not among `items`, so they count neither as open nor as done.
+ */
+type PlanPhase = {
+    id: string;
+    title: string;
+    items: ChecklistItem[];
+    deferred?: DeferredItem[];
+    touched?: true;
+};
+/** The line that opens a phase's review gate: `**Review-Gate:**`, `**Review gate** (…)`. */
+declare const isReviewGateLine: (line: string) => boolean;
+/** A heading of level three or higher, which ends the section of a phase. */
+declare const endsPhase: (line: string) => boolean;
+declare const isCheckboxLine: (line: string) => boolean;
+declare const isOpenCheckboxLine: (line: string) => boolean;
+declare const phaseHeadingPattern: (language: PlanLanguage) => RegExp;
+/**
+ * The phase an open checkbox line is moved to with `→ P<n>` at its end; null for any other line, a ticked box,
+ * a ✅/⬜ table row, and an arrow to the box's own phase `phaseId`. The one rule the parser and the tally share.
+ */
+declare const deferralTarget: (line: string, phaseId: string) => string | null;
+/**
+ * Open checkboxes that carry `→ P<n>` somewhere other than at the end of the line. `deferralTarget` reads the arrow
+ * only there, so such a box counts as open in its own phase without a word; `jh check` refuses it. In an
+ * open checkbox the phase arrow stands only at the end, also where it would be meant as prose (`→ P2 prüfen`).
+ */
+declare const misplacedDeferrals: (markdown: string) => MisplacedDeferral[];
+/**
+ * Every `### Phase <id>` section, and every `## <id> — title` section, with its checkboxes. A
+ * section runs to the next heading of level three or higher, so a review-gate list or a `####`
+ * sub-heading inside the phase still counts. A phase without checkboxes of its own that points at
+ * a section (``Siehe `## Dokumentation` ``) counts that section's items, so it is done when the
+ * section is. An open checkbox ending in `→ P<n>` is kept under `deferred` and listed in phase `<n>` as open.
+ */
+declare const parsePlanPhases: (markdown: string, language: PlanLanguage) => PlanPhase[];
+
+/** A `### Phase` heading (1-based line) whose section has tasks and neither a review gate nor the line saying why not. */
+type PhaseWithoutGate = {
+    line: number;
+    id: string;
+    title: string;
+};
+/** A row of the lanes table (1-based line) whose phases cell names no phase id. */
+type RowWithoutPhase = {
+    line: number;
+    lane: string;
+    phases: string;
+};
+/**
+ * A `### Phase` heading (1-based line) whose tasks are all ticked on the base branch while its own section still
+ * has open checkboxes not moved on with `→ P<n>` (`openLines`, 1-based).
+ */
+type MergedPhaseWithOpenBoxes = PhaseWithoutGate & {
+    openLines: number[];
+};
+/** The ids of the `### Phase` headings of a plan. */
+declare const phaseIdsOfPlan: (markdown: string, language: PlanLanguage) => Set<string>;
+/**
+ * The phases a plan gained against `previousIds` (its phase ids before the change) that have checkboxes but
+ * neither a review gate nor a `**Kein Review-Gate:** <reason>` line. A phase without checkboxes of its own (one
+ * that points at `## Dokumentation`) has nothing to gate; phases the plan already had are not read, so an old
+ * plan does not turn red when it is touched.
+ */
+declare const newPhasesWithoutReviewGate: (markdown: string, language: PlanLanguage, previousIds: ReadonlySet<string>) => PhaseWithoutGate[];
+/** Whether the document has a lanes table (`## Spuren`): a board, not a plan. */
+declare const hasLanesTable: (markdown: string, language: PlanLanguage) => boolean;
+/**
+ * The phases of `markdown` that are merged but not closed: on the base branch (`base`, the plan there) every task
+ * before the review gate is ticked, the change does not tick the phase further, and its own section still has open
+ * checkboxes, gate boxes included, that no `→ P<n>` at their end moves on. A phase the base branch lacks, or one
+ * with an open task there, is still being worked on.
+ */
+declare const mergedPhasesWithOpenBoxes: (markdown: string, base: string, language: PlanLanguage) => MergedPhaseWithOpenBoxes[];
+/**
+ * The rows of the lanes table (`## Spuren`) that are not in `previousLines` word for word and whose phases cell
+ * names no phase id (`P10c`), so neither the view nor the watcher can tie that step to a phase. The table is read
+ * as `parseSprintLanes` reads it (its first table, a lane closed when any of its rows says so); rows of a closed
+ * lane are history and stay out.
+ */
+declare const boardRowsWithoutPhase: (markdown: string, language: PlanLanguage, previousLines: ReadonlySet<string>) => RowWithoutPhase[];
+
+/**
+ * `title` is null when the sprint names a phase the plan does not have; `touched` and `deferred` carry the plan
+ * phase's own, and the deferred checkboxes are in neither `done` nor `total`.
+ */
+type PhaseProgress = {
+    id: string;
+    title: string | null;
+    done: number;
+    total: number;
+    items: ChecklistItem[];
+    deferred?: DeferredItem[];
+    touched?: true;
+};
+type StepProgress = {
+    step: PlanStep;
+    phases: PhaseProgress[];
+};
+type LaneProgress = {
+    lane: SprintLane;
+    steps: StepProgress[];
+    current: {
+        stepIndex: number;
+        phaseId: string;
+    } | null;
+    done: number;
+    total: number;
+};
+/** Parsed phases per plan link, as the sprint table spells the link; a missing key is an unread plan. */
+type PlansByHref = Record<string, PlanPhase[]>;
+declare const sumPhases: (phases: readonly PhaseProgress[]) => {
+    done: number;
+    total: number;
+};
+/**
+ * The ids of a step that show a phase of their own. An id the plan lacks (`5b`) falls back to its
+ * base phase (`5`); when the step already names that phase by its own id, or an earlier id fell
+ * back to it, the fallback would list the same tasks twice, so it is dropped. A lone fallback
+ * stays: the sprint line `P4a` finds phase 4 in the plans that have no `4a`.
+ */
+declare const keptPhaseIds: (phases: PlanPhase[], ids: readonly string[]) => string[];
+/**
+ * A phase the lane ticked to the end in its worktree while the base branch does not carry those ticks yet: still
+ * the lane's work until it is merged, not a finished phase.
+ */
+declare const isTickedUnmerged: (phase: PhaseProgress) => boolean;
+/**
+ * The phase a lane works on: the one its newest board row names (`newestRowPhase`), so ticks the lane set in older
+ * phases while tidying the plan do not take over; when that row decides nothing, the ticks do (`phaseFromTicks`).
+ * A phase ticked to the end stays current until the base branch carries its ticks.
+ */
+declare const currentPhaseOf: (steps: readonly StepProgress[]) => LaneProgress["current"];
+/** Progress of a lane over the phases its steps name; `currentPhaseOf` picks the current phase. */
+declare const laneProgress: (lane: SprintLane, plans: PlansByHref) => LaneProgress;
+declare const currentPhase: (progress: LaneProgress) => PhaseProgress | null;
+/** The item being worked on: the first open checkbox of a phase in plan order, a review-gate item included; null when none is open. */
+declare const activeItem: (phase: Pick<PhaseProgress, "items">) => ChecklistItem | null;
+/** The sidebar title of a lane, e.g. `P4 · 7/12` or `P4 · 12/12` while ticked and not merged; null when nothing of the lane could be counted. */
+declare const shortTitle: (progress: LaneProgress) => string | null;
+
+/** What a sprint document says around its lanes table: its goal and its history. */
+type SprintPlanRow = {
+    cells: string[];
+    title: string | null;
+    href: string | null;
+};
+/** One table of the plans section: the line above it (`**Folgepläne …:**`), its header and its rows. */
+type SprintPlanTable = {
+    caption: string | null;
+    header: string[];
+    rows: SprintPlanRow[];
+};
+type SprintDocument = {
+    /** The tables of the plans section (core plans, follow-up plans), each row with the plan it names. */
+    planTables: SprintPlanTable[];
+    /** The paragraphs of the goal section, or of the text before the first section when there is none. */
+    goal: string[];
+    history: {
+        header: string[];
+        rows: string[][];
+    };
+};
+declare const readSprintDocument: (markdown: string, language: PlanLanguage) => SprintDocument;
+/**
+ * The `Depends on` cell of each phase from the plan's dependency table, by phase id (`4`, `4b`). The
+ * first cell of a row starts with the id (`3 — Sync-Engine`); a plan without the table gives an empty map.
+ */
+declare const readPhaseDependencies: (planMarkdown: string, language: PlanLanguage) => Record<string, string>;
+
+export { type ChecklistItem, type DeferredItem, type DriftFinding, LANGUAGE_NAME, type LaneProgress, type MergedPhaseWithOpenBoxes, type MisplacedDeferral, PHASE_ID_PREFIX, PLAN_LANGUAGE, PLAN_STATUS, PLAN_VOCABULARY, type PhaseProgress, type PhaseTally, type PhaseWithoutGate, type PlanHeader, type PlanLanguage, type PlanPhase, type PlanStatus, type PlanStep, type PlanVocabulary, type PlansByHref, type RowWithoutPhase, type SprintDocument, type SprintLane, type SprintPlanRow, type SprintPlanTable, type StatusWord, type StepProgress, activeItem, boardRowsWithoutPhase, classifyStatus, countDecisions, currentPhase, currentPhaseOf, deferralTarget, endsPhase, findDrift, hasLanesTable, isCheckboxLine, isOpenCheckboxLine, isPlanLanguage, isReviewGateLine, isTickedUnmerged, keptPhaseIds, laneNameOf, laneProgress, mergedPhasesWithOpenBoxes, misplacedDeferrals, newPhasesWithoutReviewGate, parsePlanPhases, parseSprintLanes, phaseHeading, phaseHeadingPattern, phaseIdsOfCell, phaseIdsOfPlan, readPhaseDependencies, readPlanHeader, readSprintDocument, resolvePlanPath, sectionHeading, shortTitle, sprintTitleOf, sumPhases, tallyPhases, withoutRepeats };