cans-spec 0.3.0 → 0.5.0

package/src/core/token-budget.ts

@@ -108,9 +108,22 @@ export function buildReadPlan(
   }
 
   const backRefFiles = new Set<string>();
+  // §26 step 3 forward-ref tier (QA-17 F28): the files the canonical home
+  // POINTS TO — targets of see: refs made from the home file — connect at 40.
+  // (Back-refs, the files that point AT the home, stay 60; a file that is
+  // both keeps the higher tier.)
+  const forwardFiles = new Set<string>();
   if (home !== null) {
     for (const bp of backPointers) {
       if (targetMatchesKey(bp.toFile, home.file)) backRefFiles.add(bp.fromFile);
+      if (bp.fromFile === home.file) {
+        for (const key of allFiles.keys()) {
+          if (targetMatchesKey(bp.toFile, key)) {
+            forwardFiles.add(key);
+            break;
+          }
+        }
+      }
     }
   }
   for (const key of allFiles.keys()) {
@@ -119,6 +132,10 @@ export function buildReadPlan(
       items.set(key, { file: key, anchor: null, reason: 'see: back-ref', score: 60, estTokens: tokens(key), rank: 2 });
       continue;
     }
+    if (forwardFiles.has(key)) {
+      items.set(key, { file: key, anchor: null, reason: 'forward ref', score: 40, estTokens: tokens(key), rank: 3 });
+      continue;
+    }
     const mentions = flattenNodes(allFiles.get(key)!).some(n => n.text.toLowerCase().includes(lc));
     if (mentions) {
       items.set(key, { file: key, anchor: null, reason: 'mentions concept', score: 20, estTokens: tokens(key), rank: 3 });
@@ -182,10 +199,14 @@ export function buildReadPlan(
   const plan: BudgetReadPlanItem[] = [];
   const skipped: string[] = [];
   let totalTokens = 0;
-  let cut = false;
+  // §26 step 4 (issue #16): best-effort greedy packing. Items are walked in
+  // score order and each item that fits under the remaining budget is
+  // planned. An item that does not fit is skipped (listed in `skipped`) but
+  // does NOT cut the walk — cheaper lower-scored items that still fit are
+  // considered, so a limit below the canonical home (score 100) can still
+  // afford a cheaper back-ref (score 60) instead of yielding plan: [].
   for (const item of sorted) {
-    if (cut || totalTokens + item.estTokens > budgetLimit) {
-      cut = true;
+    if (totalTokens + item.estTokens > budgetLimit) {
       skipped.push(item.file);
       continue;
     }
@@ -198,6 +219,16 @@ export function buildReadPlan(
   for (const key of allFiles.keys()) {
     if (!items.has(key)) skipped.push(key);
   }
+  // §26 step 4 (QA-17 F25): skipped lists EVERY file not in the plan — active
+  // task files are in budget scope (§22), so a task file with no connection
+  // to the concept (never scored into `items`) is listed too, never
+  // invisible. Planned-but-unaffordable task files already landed in skipped
+  // via the packing loop above.
+  if (activeTaskPaths !== undefined) {
+    for (const taskPath of activeTaskPaths) {
+      if (!items.has(taskPath)) skipped.push(taskPath);
+    }
+  }
   skipped.sort();
 
   const usagePercent = budgetLimit > 0

package/src/types.ts

@@ -33,6 +33,12 @@ export interface BackPointer {
   fromFile: string;
   fromLine: number;
   toFile: string;
+  /** The anchor side of the back-pointer. For graph-built back-pointers
+   *  (buildRefGraph): the ref's raw anchor token, null for file-level refs.
+   *  For extracted `<!-- ref-by: ... -->` comments (extractBackPointers,
+   *  issue #19): the text of the node whose bullet line carries the comment
+   *  (INLINE form — a node mark), or null when the comment stands on its own
+   *  line (STANDALONE form — a file-level mark). */
   toAnchor: string | null;
 }
 
@@ -48,6 +54,10 @@ export interface Issue {
   category: IssueCategory;
   message: string;
   suggestion?: string;
+  /** issue #41: machine-readable dotted rule key (e.g. "refs.broken.file",
+   *  "structure.node_length.max") — stable vocabulary for report grouping and
+   *  agent consumption. Optional so non-engine Issue constructors stay legal. */
+  rule?: string;
 }
 
 // ── Rules ──
@@ -160,6 +170,13 @@ export interface CheckResult extends CommandResult {
   errorCount: number;
   warningCount: number;
   backPointersUpdated: number;
+  /** Issue #11: spec-relative paths of the files --fix actually rewrote
+   *  (sorted). Empty without --fix or when nothing needed a write; with a
+   *  [file] filter only matching files can ever appear here. */
+  backPointersUpdatedFiles: string[];
+  /** issue #41: wall-clock duration of the whole checkWorkspace run,
+   *  rounded to whole ms (0 for the static checkFail paths). */
+  elapsedMs: number;
   /** §22/§36: human-facing one-line summary of the active _rules.yaml limits (QA-02 F17). */
   rulesSummary?: string;
 }