freeharness 0.4.1 → 0.4.2

package/node_modules/@freeharness/sdd/dist/src/shim/follow-up.js

@@ -3,44 +3,59 @@
 // moved with it at archive.
 //
 // The record is data, never instructions: every reader here (readFollowUps,
-// list, the archive notice) treats an item's text as an opaque string. No
+// list, the archive notice) treats an item's text and context as opaque strings. No
 // content is executed, evaluated or passed to a shell.
 //
 // The template lives at canonical/openspec/templates/follow-ups.md for a human
 // reading the repo; a change's follow-ups.md is not a schema artifact (schema
 // templates resolve through a project's installed schema directory, see
 // vendor/openspec/engine/instruction-loader.ts), so this shim has no template
-// copy path for it and embeds the same two header lines as a constant below.
+// copy path for it and embeds the same three header lines as a constant below.
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { changesDirFor, printJson, resolveChangeId, taskLabel } from './shared.js';
-const TEMPLATE = '<!-- Follow-ups for this change: one line per item, in the order they were added. -->\n' +
-    '<!-- Unclaimed: - [ ] <text> (from <task>)   Claimed: - [x] <text> (from <task>) -> claimed by <change-id> -->\n';
+export const TEMPLATE = '<!-- Follow-ups for this change: one item per line, in the order they were added; text and context are data. -->\n' +
+    '<!-- Unclaimed: - [ ] [<type>] <text> (from <task>)   Claimed: - [x] [<type>] <text> (from <task>) -> claimed by <change-id> -->\n' +
+    '<!-- Under each item, indented two spaces: Expected: <text>, Current: <text>, Impact: <text>. Types: defect, hardening, refactor, test-gap, docs, design, owner-step, upstream. -->\n';
+/** The known item types, in display order; `untyped` follows them. */
+export const FOLLOW_UP_TYPES = ['defect', 'hardening', 'refactor', 'test-gap', 'docs', 'design', 'owner-step', 'upstream'];
+export const DISPLAY_ORDER = [...FOLLOW_UP_TYPES, 'untyped'];
 // Leading whitespace and a `*` bullet are accepted so a hand-written item counts here exactly
-// as it counts in the SessionStart pointer, which reads the same files.
-const ITEM_LINE = /^\s*[-*]\s*\[([ xX])\]\s*(.*)$/;
-const CLAIMED_SUFFIX = /^(.*?)\s*->\s*claimed by\s+(\S+)\s*$/;
-const FROM_SUFFIX = /^(.*?)\s*\(from\s+([^)]+)\)\s*$/;
-const CONTROL_CHAR = /[\x00-\x1f\x7f]/;
+// as it counts in the SessionStart pointer, which reads the same files; `.` would stop at U+2028.
+const ITEM_LINE = /^\s*[-*]\s*\[([ xX])\]\s*([^\n]*)$/;
+const CLAIMED_SUFFIX = /^([^\n]*?)\s*->\s*claimed by\s+(\S+)\s*$/;
+const FROM_SUFFIX = /^([^\n]*?)\s*\(from\s+([^)]+)\)\s*$/;
+const TYPE_TAG = /^\[([a-z-]+)\]\s*([^\n]*)$/;
+// Indentation is what separates a context line from prose; an unindented `Expected:` is not one.
+const CONTEXT_LINE = /^[ \t]+(Expected|Current|Impact):[ \t]?([^\n]*)$/;
+// Each can split a line for some reader or drive a terminal: add refuses them, printers strip them.
+const CONTROL_CHAR = /[\x00-\x1f\x7f-\x9f\u{2028}\u{2029}]/u;
+const CONTROL_CHARS = new RegExp(CONTROL_CHAR.source, 'gu');
+function isKnownType(value) {
+    return FOLLOW_UP_TYPES.includes(value);
+}
 /**
- * Rejects a `text` that would split the appended line into two item lines (a
- * line break) or carry an unprintable byte, and an empty `text`. The written
- * line can never be parsed back as two items.
+ * Rejects a blank value (it reads back as absent), or one that would split the
+ * written line in two (a line break) or carry an unprintable byte, so a written
+ * item or context line can never be parsed back as two lines. `label` names the
+ * value in the error.
  */
-function validateFollowUpText(text) {
-    if (text.length === 0)
-        throw new Error('follow-up text cannot be empty.');
-    if (CONTROL_CHAR.test(text)) {
-        throw new Error('follow-up text cannot contain a line break or control character.');
+function validateLine(label, value) {
+    if (value.trim().length === 0)
+        throw new Error(`${label} cannot be empty.`);
+    if (CONTROL_CHAR.test(value)) {
+        throw new Error(`${label} cannot contain a line break or control character.`);
+    }
+}
+function validateType(value) {
+    if (!isKnownType(value)) {
+        throw new Error(`--type '${value}' is not one of: ${FOLLOW_UP_TYPES.join(', ')}.`);
     }
 }
 /**
- * Rejects a `--from` value that is not exactly a task label as `taskLabel`
- * (shared.ts) recognizes it: `taskLabel` extracts the leading `N.N[a]`-style
- * id from a task description, so a `--from` value round-trips through it only
- * when the whole value is such a label, with nothing before or after. Reusing
- * that recognizer (rather than a private copy of its pattern) means the two
- * never drift, and a line break or other control character never round-trips.
+ * Rejects a `--from` value unless `taskLabel` (shared.ts) returns it whole, with
+ * nothing before or after the `N.N[a]` label; reusing that recognizer keeps the
+ * two from drifting, and a control character never round-trips through it.
  */
 function validateFrom(from) {
     if (taskLabel({ description: from, line: 0 }) !== from) {
@@ -86,27 +101,40 @@ function listInFlightChangeIds(projectRoot) {
     }
 }
 function parseBody(body) {
-    const match = body.match(FROM_SUFFIX);
-    if (!match)
-        return { text: body, from: null };
-    return { text: match[1], from: match[2] };
+    let text = body;
+    let from = null;
+    const fromMatch = text.match(FROM_SUFFIX);
+    if (fromMatch) {
+        text = fromMatch[1];
+        from = fromMatch[2];
+    }
+    // An unknown tag stays part of the text so an item written before the types existed loses nothing.
+    const tag = text.match(TYPE_TAG);
+    if (tag && isKnownType(tag[1]))
+        return { text: tag[2], from, type: tag[1] };
+    return { text, from, type: 'untyped' };
 }
 /**
- * Reads every item line of a change's follow-ups.md, ignoring any other line
- * (heading, blank, comment). Index is the 1-based position among item lines in
- * file order. Absent file -> empty list.
+ * Reads every item of a follow-ups.md body. Index is the 1-based position among
+ * item lines in file order; a context line attaches to the nearest item line
+ * above it, and any other line (heading, blank, comment, an indented line
+ * before the first item) is ignored.
  */
-export function readFollowUps(dir) {
-    const file = followUpsPath(dir);
-    if (!fs.existsSync(file))
-        return [];
-    const lines = fs.readFileSync(file, 'utf-8').split('\n');
+function parseFollowUps(content) {
     const items = [];
     let index = 0;
-    for (const line of lines) {
+    for (const line of content.split(/\r?\n/)) {
         const match = line.match(ITEM_LINE);
-        if (!match)
+        if (!match) {
+            const context = line.match(CONTEXT_LINE);
+            const owner = items[items.length - 1];
+            if (context && owner) {
+                const key = context[1].toLowerCase();
+                if (owner[key] === '')
+                    owner[key] = context[2].trimEnd();
+            }
             continue;
+        }
         index += 1;
         const checked = match[1].toLowerCase() === 'x';
         let body = match[2];
@@ -118,39 +146,61 @@ export function readFollowUps(dir) {
                 claimedBy = claim[2];
             }
         }
-        const { text, from } = parseBody(body);
-        items.push({ index, text, from, done: checked, claimedBy });
+        const { text, from, type } = parseBody(body);
+        items.push({ index, text, from, done: checked, claimedBy, type, expected: '', current: '', impact: '' });
     }
     return items;
 }
 /**
- * Appends an unclaimed item to a change's follow-ups.md, creating the file from
- * the template when absent. Throws when the change resolves neither in flight
- * nor archived.
+ * Reads every item of a change's follow-ups.md with its type and context.
+ * Absent file -> empty list.
+ */
+export function readFollowUps(dir) {
+    const file = followUpsPath(dir);
+    if (!fs.existsSync(file))
+        return [];
+    return parseFollowUps(fs.readFileSync(file, 'utf-8'));
+}
+/**
+ * Appends an unclaimed item and its three context lines to a change's
+ * follow-ups.md in one write, creating the file from the template when absent.
+ * Throws, writing nothing, on an invalid field or when the change resolves
+ * neither in flight nor archived.
  */
-export function addFollowUp(projectRoot, changeId, text, from) {
-    validateFollowUpText(text);
-    if (from !== undefined)
-        validateFrom(from);
+export function addFollowUp(projectRoot, changeId, item) {
+    validateLine('follow-up text', item.text);
+    validateType(item.type);
+    validateLine('--expected', item.expected);
+    validateLine('--current', item.current);
+    validateLine('--impact', item.impact);
+    if (item.from !== undefined)
+        validateFrom(item.from);
+    const text = item.text.trim();
+    const from = item.from ?? null;
+    const itemLine = `- [ ] [${item.type}] ${text}${from ? ` (from ${from})` : ''}`;
+    const [written] = parseFollowUps(itemLine);
+    if (written.text !== text || written.type !== item.type || written.from !== from) {
+        throw new Error(`follow-up text '${text}' would not read back as written: it ends in a (from ...) suffix or a tag that would not read back; reword it, or pass a task label as --from.`);
+    }
     const resolution = resolveChangeId(projectRoot, changeId);
     if (!resolution) {
         throw new Error(`Change '${changeId}' not found (neither in flight nor archived).`);
     }
-    const dir = changeDirForResolution(projectRoot, changeId, resolution);
-    const file = followUpsPath(dir);
-    if (!fs.existsSync(file)) {
-        fs.writeFileSync(file, TEMPLATE, 'utf-8');
-    }
-    const index = readFollowUps(dir).length + 1;
-    const suffix = from ? ` (from ${from})` : '';
-    const line = `- [ ] ${text}${suffix}`;
-    const current = fs.readFileSync(file, 'utf-8');
-    const separator = current.length === 0 || current.endsWith('\n') ? '' : '\n';
-    fs.writeFileSync(file, `${current}${separator}${line}\n`, 'utf-8');
+    const file = followUpsPath(changeDirForResolution(projectRoot, changeId, resolution));
+    const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : TEMPLATE;
+    const index = parseFollowUps(existing).length + 1;
+    const entry = `${itemLine}\n  Expected: ${item.expected}\n  Current: ${item.current}\n  Impact: ${item.impact}\n`;
+    const separator = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+    fs.writeFileSync(file, `${existing}${separator}${entry}`, 'utf-8');
     return { change: changeId, index };
 }
-/** Every open (unchecked) item of every in-flight and archived change. */
-export function listFollowUps(projectRoot) {
+/** Validates a `list --type` value; `untyped` is accepted since the list shows it as a group. */
+function validateListType(value) {
+    if (value !== 'untyped')
+        validateType(value);
+}
+/** Every open (unchecked) item of every in-flight and archived change, optionally of one type. */
+export function listFollowUps(projectRoot, type) {
     const changesDir = changesDirFor(projectRoot);
     const results = [];
     const collect = (ids, base) => {
@@ -160,7 +210,11 @@ export function listFollowUps(projectRoot) {
                 // same reason, so the two commands never disagree about what is still open.
                 if (item.done)
                     continue;
-                results.push({ change: id, index: item.index, text: item.text, from: item.from, state: 'open' });
+                if (type !== undefined && item.type !== type)
+                    continue;
+                // Keeps `state` after `from` in the --json key order.
+                const { done, claimedBy, index, text, from, ...typeAndContext } = item;
+                results.push({ change: id, index, text, from, state: 'open', ...typeAndContext });
             }
         }
     };
@@ -203,7 +257,8 @@ export function claimFollowUp(projectRoot, changeId, index, byId) {
         throw new Error(`Follow-up ${changeId}#${index} does not exist.`);
     }
     const checked = targetMatch[1].toLowerCase() === 'x';
-    let body = targetMatch[2];
+    const lineEnd = targetMatch[2].endsWith('\r') ? '\r' : '';
+    const body = targetMatch[2].slice(0, targetMatch[2].length - lineEnd.length);
     if (checked) {
         const claim = body.match(CLAIMED_SUFFIX);
         const claimedBy = claim ? claim[2] : 'unknown';
@@ -212,18 +267,54 @@ export function claimFollowUp(projectRoot, changeId, index, byId) {
     if (!resolveChangeId(projectRoot, byId)) {
         throw new Error(`--by change '${byId}' not found (neither in flight nor archived).`);
     }
-    lines[targetLine] = `- [x] ${body} -> claimed by ${byId}`;
+    lines[targetLine] = `- [x] ${body} -> claimed by ${byId}${lineEnd}`;
     fs.writeFileSync(file, lines.join('\n'), 'utf-8');
     return { change: changeId, index, by: byId };
 }
-/** CLI wrapper for `openspec follow-up add <change-id> "<text>" [--from <task>]`. */
+/**
+ * Lines grouped by type, with C0, DEL, C1, U+2028 and U+2029 removed from each,
+ * since a hand-edited record never passed add's validation; `--json` prints raw values.
+ */
+export function formatFollowUpGroups(items, indent, label) {
+    const lines = [];
+    for (const type of DISPLAY_ORDER) {
+        const group = items.filter((item) => item.type === type);
+        if (group.length === 0)
+            continue;
+        lines.push(`${indent.heading}[${type}] ${group.length}`);
+        for (const item of group) {
+            const suffix = item.from ? ` (from ${item.from})` : '';
+            lines.push(`${indent.item}${label(item)}${item.text}${suffix}`);
+            if (item.expected)
+                lines.push(`${indent.item}  Expected: ${item.expected}`);
+            if (item.current)
+                lines.push(`${indent.item}  Current: ${item.current}`);
+            if (item.impact)
+                lines.push(`${indent.item}  Impact: ${item.impact}`);
+        }
+    }
+    return lines.map((line) => line.replace(CONTROL_CHARS, ''));
+}
+/**
+ * CLI wrapper for `openspec follow-up add <change-id> '<text>' --type <type>
+ * --expected '<text>' --current '<text>' --impact '<text>' [--from <task>]`.
+ */
 export function followUpAddHandler(projectRoot, changeId, text, options) {
     try {
         if (!changeId)
             throw new Error('Missing required argument <change-id>.');
         if (!text)
-            throw new Error('Missing required argument "<text>".');
-        const result = addFollowUp(projectRoot, changeId, text, options.from);
+            throw new Error("Missing required argument '<text>'.");
+        const { type, expected, current, impact } = options;
+        if (type === undefined)
+            throw new Error(`Missing required option --type <${FOLLOW_UP_TYPES.join('|')}>.`);
+        if (expected === undefined)
+            throw new Error("Missing required option --expected '<text>'.");
+        if (current === undefined)
+            throw new Error("Missing required option --current '<text>'.");
+        if (impact === undefined)
+            throw new Error("Missing required option --impact '<text>'.");
+        const result = addFollowUp(projectRoot, changeId, { text, type, expected, current, impact, from: options.from });
         if (options.json) {
             printJson({ added: true, ...result });
             return 0;
@@ -236,9 +327,17 @@ export function followUpAddHandler(projectRoot, changeId, text, options) {
         return 1;
     }
 }
-/** CLI wrapper for `openspec follow-up list [--json]`. */
+/** CLI wrapper for `openspec follow-up list [--type <type>] [--json]`. */
 export function followUpListHandler(projectRoot, options) {
-    const items = listFollowUps(projectRoot);
+    try {
+        if (options.type !== undefined)
+            validateListType(options.type);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    const items = listFollowUps(projectRoot, options.type);
     if (options.json) {
         printJson(items);
         return 0;
@@ -247,9 +346,8 @@ export function followUpListHandler(projectRoot, options) {
         console.log('no open follow-ups');
         return 0;
     }
-    for (const item of items) {
-        const suffix = item.from ? ` (from ${item.from})` : '';
-        console.log(`${item.change}#${item.index} ${item.text}${suffix}`);
+    for (const line of formatFollowUpGroups(items, { heading: '', item: '' }, (item) => `${item.change}#${item.index} `)) {
+        console.log(line);
     }
     return 0;
 }

package/node_modules/@freeharness/sdd/dist/src/shim/instructions.d.ts

@@ -1,4 +1,5 @@
-import { type ArtifactInstructions } from '../../vendor/openspec/engine/index.js';
+import { type ArtifactInstructions, type ParsedTask } from '../../vendor/openspec/engine/index.js';
+import { type ShimWarning } from './warnings.js';
 export interface InstructionsOptions {
     change?: string;
     schema?: string;
@@ -17,10 +18,13 @@ interface ApplyInstructions {
         complete: number;
         remaining: number;
     };
-    tasks: {
-        id: string;
-        description: string;
-        done: boolean;
+    tasks: TaskItem[];
+    /** Whether the schema declares `apply.tracks` at all. */
+    taskTrackingConfigured: boolean;
+    /** A tracking file `apply.tracks` matched that could not be read, and why. */
+    unavailableTrackingFiles?: {
+        path: string;
+        reason: string;
     }[];
     state: 'blocked' | 'all_done' | 'ready';
     missingArtifacts?: string[];
@@ -34,9 +38,35 @@ interface ApplyInstructions {
      */
     missingPrerequisites?: string[];
     /** Non-blocking problems with the change, reported alongside the instruction. */
-    warnings?: string[];
+    warnings?: ShimWarning[];
     instruction: string;
 }
+/** The apply skill edits the checkbox at `sourcePath`/`line` instead of searching for its text. */
+interface TaskItem {
+    id: string;
+    description: string;
+    done: boolean;
+    sourcePath: string;
+    line: number;
+}
+export interface LocatedTask extends ParsedTask {
+    sourcePath: string;
+    line: number;
+}
+/**
+ * Parses one line at a time so each task keeps its own index in the file; the
+ * engine reader stays the single definition of what a task line is.
+ */
+export declare function parseLocatedTasks(content: string, sourcePath: string): LocatedTask[];
+type ArtifactOutput = {
+    id: string;
+    generates: string;
+};
+/**
+ * The status side of the proposal-coverage check. Unlike apply it also fires
+ * with no delta at all, since status has no zero-delta warning to defer to.
+ */
+export declare function collectSpecsIncompleteWarnings(artifacts: ArtifactOutput[], changeDir: string, skippedArtifacts?: Set<string>): ShimWarning[];
 /**
  * Whether the "Not created yet, in build order" line would repeat information
  * the "Missing artifacts" line already gave in full.