cans-spec 0.1.0

package/src/core/token-budget.ts

@@ -0,0 +1,284 @@
+import { readFileSync } from 'fs';
+import { basename, relative } from 'path';
+import type {
+  OutlineNode, BackPointer, TokenBudgetRules,
+  BudgetReadPlanItem, BudgetReadResult, BudgetWriteResult,
+} from '../types';
+import { flattenNodes, parseOutline } from './outline';
+import { targetMatchesKey } from './refs';
+
+export function estimateTokens(text: string, charsPerToken: number): number {
+  return Math.ceil(text.length / charsPerToken);
+}
+
+/** QA-03 F12: file paths in budget output are cwd-relative, never absolute
+ *  (workspace keys are already relative and pass through untouched). */
+function relPath(file: string): string {
+  if (!file.startsWith('/')) return file;
+  return relative(process.cwd(), file) || file;
+}
+
+function serializedNodeText(nodes: OutlineNode[]): string {
+  return flattenNodes(nodes).map(n => n.text).join('\n');
+}
+
+/** Token estimate for a workspace key (loaded nodes) or a raw file path (content read). */
+function fileTokens(allFiles: Map<string, OutlineNode[]>, file: string, cpt: number): number {
+  const nodes = allFiles.get(file);
+  if (nodes !== undefined) return estimateTokens(serializedNodeText(nodes), cpt);
+  try {
+    return estimateTokens(readFileSync(file, 'utf-8'), cpt);
+  } catch {
+    return 0;
+  }
+}
+
+function readNodesFor(file: string, allFiles: Map<string, OutlineNode[]>): OutlineNode[] | null {
+  const loaded = allFiles.get(file);
+  if (loaded !== undefined) return loaded;
+  try {
+    return parseOutline(readFileSync(file, 'utf-8'), file);
+  } catch {
+    return null;
+  }
+}
+
+/** Canonical home: candidate nodes (text mentions concept) ranked by
+ *  child count DESC → indent ASC → file ASC → line ASC. */
+export function findCanonicalHome(
+  concept: string,
+  allFiles: Map<string, OutlineNode[]>,
+): { file: string; anchor: string | null } | null {
+  const lc = concept.toLowerCase();
+  const candidates: Array<{ file: string; node: OutlineNode }> = [];
+  for (const [file, nodes] of allFiles) {
+    for (const node of flattenNodes(nodes)) {
+      if (node.text.toLowerCase().includes(lc)) candidates.push({ file, node });
+    }
+  }
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => {
+    const byChildren = b.node.children.length - a.node.children.length;
+    if (byChildren !== 0) return byChildren;
+    const byIndent = a.node.indent - b.node.indent;
+    if (byIndent !== 0) return byIndent;
+    if (a.file !== b.file) return a.file < b.file ? -1 : 1;
+    return a.node.line - b.node.line;
+  });
+  const top = candidates[0];
+  return { file: top.file, anchor: top.node.text };
+}
+
+interface RankedItem extends BudgetReadPlanItem {
+  rank: number; // tie-break after score: active task first, then canonical home
+}
+
+export function buildReadPlan(
+  concept: string,
+  allFiles: Map<string, OutlineNode[]>,
+  backPointers: BackPointer[],
+  rules: TokenBudgetRules,
+  limit?: number,
+  taskFile?: string,
+  activeTaskPaths?: string[],
+): BudgetReadResult {
+  const lc = concept.toLowerCase();
+  const budgetLimit = limit ?? rules.default_limit;
+  const cpt = rules.estimate_chars_per_token;
+  const home = findCanonicalHome(concept, allFiles);
+  const tokens = (f: string): number => fileTokens(allFiles, f, cpt);
+  const items = new Map<string, RankedItem>();
+
+  if (taskFile !== undefined) {
+    items.set(taskFile, {
+      file: taskFile, anchor: null, reason: 'active task', score: 100,
+      estTokens: tokens(taskFile), rank: 0,
+    });
+  }
+  if (home !== null) {
+    items.set(home.file, {
+      file: home.file, anchor: home.anchor, reason: 'canonical home', score: 100,
+      estTokens: tokens(home.file), rank: taskFile !== undefined ? 1 : 0,
+    });
+  }
+
+  const backRefFiles = new Set<string>();
+  if (home !== null) {
+    for (const bp of backPointers) {
+      if (targetMatchesKey(bp.toFile, home.file)) backRefFiles.add(bp.fromFile);
+    }
+  }
+  for (const key of allFiles.keys()) {
+    if (items.has(key)) continue;
+    if (backRefFiles.has(key)) {
+      items.set(key, { file: key, anchor: null, reason: 'see: back-ref', score: 60, estTokens: tokens(key), rank: 2 });
+      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 });
+    }
+  }
+
+  // §26 step 3: active tasks mentioning the concept score 80 and join the plan
+  // right after the canonical home.
+  if (activeTaskPaths !== undefined) {
+    for (const taskPath of activeTaskPaths) {
+      if (items.has(taskPath)) continue;
+      let content = '';
+      try {
+        content = readFileSync(taskPath, 'utf-8');
+      } catch {
+        continue;
+      }
+      if (content.toLowerCase().includes(lc)) {
+        items.set(taskPath, {
+          file: taskPath, anchor: null,
+          reason: 'active task mentions concept',
+          score: 80,
+          estTokens: estimateTokens(content, cpt),
+          rank: 2,
+        });
+      }
+    }
+  }
+
+  if (taskFile !== undefined) {
+    const taskNodes = readNodesFor(taskFile, allFiles);
+    if (taskNodes !== null) {
+      for (const node of flattenNodes(taskNodes)) {
+        for (const ref of node.refs) {
+          for (const key of allFiles.keys()) {
+            if (!targetMatchesKey(ref.file, key)) continue;
+            const existing = items.get(key);
+            if (existing !== undefined && (existing.reason === 'canonical home' || existing.reason === 'active task')) continue;
+            if (existing !== undefined) {
+              if (existing.score < 80) {
+                existing.score = 80;
+                existing.reason = 'task ref target';
+              }
+            } else {
+              items.set(key, { file: key, anchor: null, reason: 'task ref target', score: 80, estTokens: tokens(key), rank: 2 });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  const sorted = [...items.values()].sort((a, b) => {
+    const byScore = b.score - a.score;
+    if (byScore !== 0) return byScore;
+    const byRank = a.rank - b.rank;
+    if (byRank !== 0) return byRank;
+    return a.file < b.file ? -1 : a.file > b.file ? 1 : 0;
+  });
+
+  const plan: BudgetReadPlanItem[] = [];
+  const skipped: string[] = [];
+  let totalTokens = 0;
+  let cut = false;
+  for (const item of sorted) {
+    if (cut || totalTokens + item.estTokens > budgetLimit) {
+      cut = true;
+      skipped.push(item.file);
+      continue;
+    }
+    plan.push({
+      file: item.file, anchor: item.anchor, reason: item.reason,
+      score: item.score, estTokens: item.estTokens,
+    });
+    totalTokens += item.estTokens;
+  }
+  for (const key of allFiles.keys()) {
+    if (!items.has(key)) skipped.push(key);
+  }
+  skipped.sort();
+
+  const usagePercent = budgetLimit > 0
+    ? Math.round((totalTokens / budgetLimit) * 1000) / 10
+    : 0;
+  return {
+    ok: true, command: 'budget-read', exitCode: 0, concept,
+    plan: plan.map(p => ({ ...p, file: relPath(p.file) })),
+    skipped: skipped.map(relPath),
+    totalTokens, budgetLimit, usagePercent,
+  };
+}
+
+function taskMentionsConcept(
+  taskPath: string,
+  allFiles: Map<string, OutlineNode[]>,
+  lc: string,
+): boolean {
+  try {
+    return readFileSync(taskPath, 'utf-8').toLowerCase().includes(lc);
+  } catch {
+    const base = basename(taskPath);
+    for (const [key, nodes] of allFiles) {
+      if (basename(key) !== base) continue;
+      if (flattenNodes(nodes).some(n => n.refs.length === 0 && n.text.toLowerCase().includes(lc))) return true;
+    }
+    return false;
+  }
+}
+
+export function buildWritePlan(
+  concept: string,
+  allFiles: Map<string, OutlineNode[]>,
+  backPointers: BackPointer[],
+  activeTasks: string[],
+): BudgetWriteResult {
+  const lc = concept.toLowerCase();
+  const home = findCanonicalHome(concept, allFiles);
+  const homeFile = home === null ? null : home.file;
+
+  const canEdit: Array<{ file: string; anchor: string | null; reason: string }> = [];
+  if (home !== null) {
+    canEdit.push({ file: home.file, anchor: home.anchor, reason: 'canonical home' });
+  }
+  for (const taskPath of activeTasks) {
+    if (taskMentionsConcept(taskPath, allFiles, lc)) {
+      canEdit.push({ file: taskPath, anchor: null, reason: 'active task' });
+    }
+  }
+
+  const mustNotEdit: Array<{ file: string; reason: string }> = [];
+  const backPointersToUpdate: Array<{ fromFile: string; fromLine: number; toFile: string }> = [];
+  if (homeFile !== null) {
+    for (const key of allFiles.keys()) {
+      if (key === homeFile) continue;
+      let hasBackRef = false;
+      for (const bp of backPointers) {
+        if ((bp.fromFile === key || targetMatchesKey(bp.fromFile, key)) && targetMatchesKey(bp.toFile, homeFile)) {
+          hasBackRef = true;
+          break;
+        }
+      }
+      if (!hasBackRef) continue;
+      // "mentions" counts only non-ref content: see:/anchor text is a pointer, not a definition.
+      const contentMention = flattenNodes(allFiles.get(key)!).some(
+        n => n.refs.length === 0 && n.text.toLowerCase().includes(lc),
+      );
+      if (!contentMention) {
+        mustNotEdit.push({ file: key, reason: 'only has see: reference' });
+      }
+    }
+    for (const bp of backPointers) {
+      if (targetMatchesKey(bp.toFile, homeFile)) {
+        backPointersToUpdate.push({ fromFile: bp.fromFile, fromLine: bp.fromLine, toFile: homeFile });
+      }
+    }
+  }
+
+  return {
+    ok: true, command: 'budget-write', exitCode: 0, concept,
+    canEdit: canEdit.map(e => ({ ...e, file: relPath(e.file) })),
+    mustNotEdit: mustNotEdit.map(e => ({ ...e, file: relPath(e.file) })),
+    backPointersToUpdate: backPointersToUpdate.map(b => ({
+      ...b,
+      fromFile: relPath(b.fromFile),
+      toFile: relPath(b.toFile),
+    })),
+  };
+}

package/src/types.ts

@@ -0,0 +1,284 @@
+// ── Outline ──
+
+export interface RefTarget {
+  raw: string;
+  file: string;
+  anchor: string | null;
+  line: number;
+}
+
+export interface OutlineNode {
+  text: string;
+  line: number;
+  indent: number;
+  children: OutlineNode[];
+  file: string;
+  isTask: boolean;
+  isDone: boolean;
+  owner: string | null;
+  isHumanGate: boolean;
+  refs: RefTarget[];
+  hasCodeFence: boolean;
+  hasTable: boolean;
+}
+
+export interface BackPointer {
+  fromFile: string;
+  fromLine: number;
+  toFile: string;
+  toAnchor: string | null;
+}
+
+// ── Issues ──
+
+export type IssueLevel = 'error' | 'warning';
+export type IssueCategory = 'structure' | 'style' | 'refs' | 'redundancy' | 'overflow';
+
+export interface Issue {
+  file: string;
+  line: number;
+  level: IssueLevel;
+  category: IssueCategory;
+  message: string;
+  suggestion?: string;
+}
+
+// ── Rules ──
+
+/** §18 delete-key semantics: a check whose mapping key is deleted (or whose
+ *  section is deleted) is OFF. Off is encoded as `null` members — engines MUST
+ *  skip the corresponding check when a member is null/false (never compare
+ *  against null, which would coerce to 0 and flag everything). */
+export interface LengthRange {
+  min: number | null;
+  max: number | null;
+}
+
+export interface StructureRules {
+  node_length: LengthRange;
+  siblings: LengthRange;
+  depth: LengthRange;
+  single_child_collapse: boolean;
+  empty_nodes: boolean;
+}
+
+export interface StyleRules {
+  /** Deleted `prefer` disables prefer-driven style guidance (§18). */
+  prefer: 'sibling' | 'nested' | null;
+  force_nested_above: number | null;
+  force_sibling_below: number | null;
+  shared_prefix_detection: boolean;
+}
+
+export interface ContentRules {
+  tbd_allowed: boolean;
+  max_tbd_per_file: number | null;
+}
+
+export interface ReferenceRules {
+  /** Parameter (not a check): keeps its default when deleted (§18). */
+  mode: 'pointer';
+  back_pointers: boolean;
+  /** Deleted → deep-hop check off (null = skip detectDeepHops, §18 strict). */
+  max_hops: number | null;
+  orphan_check: boolean;
+  duplicate_home_check: boolean;
+}
+
+export interface RedundancyRules {
+  enabled: boolean;
+  word_frequency_threshold: number | null;
+  phrase_overlap_threshold: number | null;
+  cross_file_threshold: number | null;
+  /** Parameters (not checks): keep their defaults when deleted (§18). */
+  stopwords: string[];
+  synonyms: string[][];
+}
+
+export interface TokenBudgetRules {
+  enabled: boolean;
+  /** Parameters (not checks): budget planning keeps defaults when deleted (§18). */
+  default_limit: number;
+  estimate_chars_per_token: number;
+  /** Deleted → usage warning off (null = never warn). */
+  warn_threshold: number | null;
+}
+
+export interface OverflowRules {
+  /** Deleted → char-length check off (§18). */
+  max_node_chars: number | null;
+  /** Deleted → nothing is forced into files → no content-type flags (§16/§18). */
+  force_file_for: string[] | null;
+}
+
+export interface Rules {
+  structure: StructureRules;
+  style: StyleRules;
+  content: ContentRules;
+  references: ReferenceRules;
+  redundancy: RedundancyRules;
+  token_budget: TokenBudgetRules;
+  overflow: OverflowRules;
+}
+
+// ── Command Results ──
+
+export interface CommandResult {
+  ok: boolean;
+  command: string;
+  exitCode: number;
+}
+
+export interface InitResult extends CommandResult {
+  command: 'init';
+  created: string[];
+  skipped: string[];
+  root: string;
+  /** §37: set when init refuses (e.g. already inside a cans/ workspace). */
+  error?: string;
+}
+
+export interface CheckResult extends CommandResult {
+  command: 'check';
+  files: number;
+  nodes: number;
+  maxDepth: number;
+  refs: { total: number; broken: number; deepHops: number };
+  backPointers: { total: number; current: number; stale: number };
+  issues: Issue[];
+  errorCount: number;
+  warningCount: number;
+  backPointersUpdated: number;
+  /** §22/§36: human-facing one-line summary of the active _rules.yaml limits (QA-02 F17). */
+  rulesSummary?: string;
+}
+
+export interface NewResult extends CommandResult {
+  command: 'new';
+  change: string;
+  file: string;
+  /** §37: real diagnosis for failures (unknown kind, empty slug, no workspace). */
+  error?: string;
+  /** Set when `new` notices a condition the user should know about. */
+  warning?: string;
+}
+
+export interface DoneResult extends CommandResult {
+  command: 'done';
+  change: string;
+  gates: { human: number; humanOpen: number; tasks: number; tasksOpen: number };
+  /** §36: gate detail lines for human output. Each: { file, line, text } */
+  gateDetails?: Array<{ file: string; line: number; text: string }>;
+  archived: string | null;
+  backPointersUpdated: number;
+  /** §37: real diagnosis (task not found, no workspace, parse error). */
+  error?: string;
+}
+
+export interface StatusResult extends CommandResult {
+  command: 'status';
+  specFiles: number;
+  activeTasks: number;
+  archivedTasks: number;
+  adrCount: number;
+  tasks: { total: number; done: number; unclaimed: number; blocked: number };
+  owners: Record<string, { tasks: number; done: number }>;
+  taskFiles: Array<{
+    name: string;
+    tasksDone: number;
+    tasksTotal: number;
+    gatesDone: number;
+    gatesTotal: number;
+    blocked: boolean;
+    /** Items with `←` but no owner (§25 unclaimed semantics). */
+    unclaimed?: number;
+  }>;
+  conflicts: number;
+  /** Set when --unclaimed / --blocked / --owners filters are active.
+   *  Human printer uses these to restrict output; JSON always has full data. */
+  filter?: 'unclaimed' | 'blocked' | 'owners';
+  /** §37: set when the workspace is missing. */
+  error?: string;
+}
+
+export interface BudgetReadPlanItem {
+  file: string;
+  anchor: string | null;
+  reason: string;
+  score: number;
+  estTokens: number;
+}
+
+export interface BudgetReadResult extends CommandResult {
+  command: 'budget-read';
+  concept: string;
+  plan: BudgetReadPlanItem[];
+  skipped: string[];
+  totalTokens: number;
+  budgetLimit: number;
+  usagePercent: number;
+  /** §37: real diagnosis (usage error, no workspace, no matches). */
+  error?: string;
+}
+
+export interface BudgetWriteResult extends CommandResult {
+  command: 'budget-write';
+  concept: string;
+  canEdit: Array<{ file: string; anchor: string | null; reason: string }>;
+  mustNotEdit: Array<{ file: string; reason: string }>;
+  backPointersToUpdate: Array<{ fromFile: string; fromLine: number; toFile: string }>;
+  /** §37: real diagnosis (usage error, no workspace, empty scope). */
+  error?: string;
+}
+
+export interface ImportConflict {
+  file: string;
+  line: number;
+  cansVersion: string;
+  importVersion: string;
+  resolution: string;
+}
+
+export interface ImportResult extends CommandResult {
+  command: 'import';
+  format: string;
+  source: string;
+  newFiles: string[];
+  merged: string[];
+  conflicts: ImportConflict[];
+  /** §37: real diagnosis (usage error, source not found, parse failure). */
+  error?: string;
+  /** Set when the import was a dry run (no files written). */
+  dryRun?: boolean;
+}
+
+export interface ExportResult extends CommandResult {
+  command: 'export';
+  format: string;
+  outputDir: string;
+  filesExported: number;
+  /** §37: real diagnosis (usage error, no workspace). */
+  error?: string;
+  /** Set when the export was a dry run (no files written). */
+  dryRun?: boolean;
+}
+
+export interface VersionResult extends CommandResult {
+  command: 'version';
+  version: string;
+}
+
+// ── Converters ──
+
+export interface ExternalNode {
+  text: string;
+  indent: number;
+  isTask: boolean;
+  isDone: boolean;
+  children: ExternalNode[];
+  metadata: Record<string, string>;
+}
+
+export type MergeStrategy = 'cans-wins' | 'import-wins' | 'ask';
+export type ImportFormat = 'opml' | 'dynalist' | 'logseq' | 'obsidian';
+export type ExportFormat = ImportFormat | 'all';