cans-spec 0.1.0

package/src/core/fs.ts

@@ -0,0 +1,309 @@
+import { statSync, readdirSync, existsSync, mkdirSync, type Stats } from 'fs';
+import { join, relative, dirname, basename } from 'path';
+
+const SPEC_FILE_RE = /^\d{2}-.+\.md$/;
+
+/** Tool-specific instruction artifacts (§21 `--tool <name>`, §32): emitted
+ *  beside the specs as agent-facing instructions, never spec content — same
+ *  exclusion class as AGENTS.md (QA-09 F4: CLAUDE.md must not be discovered
+ *  as a spec file, counted by status, or exported). */
+const TOOL_ARTIFACTS = new Set(['AGENTS.md', 'CLAUDE.md', '.cursorrules']);
+
+export function exists(p: string): boolean {
+  return existsSync(p);
+}
+
+export function dirExists(p: string): boolean {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function mkdirp(p: string): void {
+  mkdirSync(p, { recursive: true });
+}
+
+export function globFiles(dir: string, pattern: string): string[] {
+  if (!dirExists(dir)) return [];
+  const g = new Bun.Glob(pattern);
+  const out = [...g.scanSync({ cwd: dir, onlyFiles: true })] as string[];
+  return out.sort();
+}
+
+/** Spec files: root-level *.md (excluding _-prefixed, AGENTS.md and other tool
+ *  artifacts) plus per-folder index.md. */
+export function discoverSpecFiles(root: string): string[] {
+  const out: string[] = [];
+  if (!dirExists(root)) return out;
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (entry.name.startsWith('_') || TOOL_ARTIFACTS.has(entry.name)) continue;
+    if (entry.isFile() && entry.name.endsWith('.md')) {
+      out.push(entry.name);
+    } else if (entry.isDirectory()) {
+      const idx = join(entry.name, 'index.md');
+      if (exists(join(root, idx))) out.push(idx);
+    }
+  }
+  return out.sort();
+}
+
+/** Detect flat-vs-folder conflicts: both `NN-name.md` AND `NN-name/index.md` exist.
+ *  §8: "Flat wins over folder. If both exist, `cans check` flags error."
+ *  Returns pairs of [flatRel, folderRel]. */
+export function detectFlatFolderConflicts(root: string): Array<[string, string]> {
+  const conflicts: Array<[string, string]> = [];
+  if (!dirExists(root)) return conflicts;
+
+  const flatFiles = new Set<string>();
+  const folderDirs = new Set<string>();
+
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (entry.name.startsWith('_') || TOOL_ARTIFACTS.has(entry.name)) continue;
+    if (entry.isFile() && SPEC_FILE_RE.test(entry.name)) {
+      flatFiles.add(entry.name);
+    } else if (entry.isDirectory() && exists(join(root, entry.name, 'index.md'))) {
+      folderDirs.add(entry.name);
+    }
+  }
+
+  for (const flat of flatFiles) {
+    const dirName = flat.replace(/\.md$/, '');
+    if (folderDirs.has(dirName)) {
+      conflicts.push([flat, `${dirName}/index.md`]);
+    }
+  }
+
+  return conflicts.sort();
+}
+
+/** Directories named like a spec file (e.g. `02-authentication.md/`) — malformed
+ *  workspace entries that discovery would silently skip (§37: report what the
+ *  user can fix instead of tolerating it). Returns the directory names. */
+export function detectMalformedSpecDirs(root: string): string[] {
+  const out: string[] = [];
+  if (!dirExists(root)) return out;
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (entry.isDirectory() && SPEC_FILE_RE.test(entry.name)) {
+      out.push(entry.name);
+    }
+  }
+  return out.sort();
+}
+
+/** Overflow target files: `.md` content files inside workspace subfolders
+ *  (e.g. `04-api/request-schema.md`) that are not spec files themselves.
+ *  §16: these must NOT contain their own `see:` refs (no chaining). */
+export function discoverOverflowTargets(root: string): string[] {
+  const out: string[] = [];
+  if (!dirExists(root)) return out;
+  const walk = (dir: string, prefix: string): void => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('_') || TOOL_ARTIFACTS.has(entry.name)) continue;
+      const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        // `*/index.md` is a folder-mode spec file, not an overflow target.
+        if (prefix !== '' && entry.name !== 'index.md') out.push(rel);
+      } else if (entry.isDirectory()) {
+        walk(join(dir, entry.name), rel);
+      }
+    }
+  };
+  walk(root, '');
+  return out.sort();
+}
+
+export function discoverActiveTasks(root: string): string[] {
+  return globFiles(join(root, '_tasks'), '*.md')
+    .map(p => join('_tasks', basename(p)))
+    .sort();
+}
+
+export function discoverArchivedTasks(root: string): string[] {
+  return globFiles(join(root, '_tasks', '_archive'), '*.md')
+    .map(p => join('_tasks', '_archive', basename(p)))
+    .sort();
+}
+
+export function discoverAdrs(root: string): string[] {
+  return globFiles(join(root, '_adr'), '*.md')
+    .map(p => join('_adr', basename(p)))
+    .filter(p => basename(p) !== '_template.md')
+    .sort();
+}
+
+/** Resolve a ref target: flat file wins, then folder index.md. null when neither exists. */
+export function resolveSpecFile(root: string, name: string): string | null {
+  const direct = join(root, name);
+  if (exists(direct) && statSync(direct).isFile()) return direct;
+  if (name.endsWith('.md')) {
+    const folderIdx = join(root, name.slice(0, -3), 'index.md');
+    if (exists(folderIdx)) return folderIdx;
+  }
+  return null;
+}
+
+// ── Workspace discovery ──
+
+function looksLikeWorkspace(dir: string): boolean {
+  if (!dirExists(dir)) return false;
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isFile() && SPEC_FILE_RE.test(entry.name)) return true;
+      if (entry.isDirectory() && entry.name === '_tasks') return true;
+      if (entry.isDirectory() && entry.name === '_adr') return true;
+      if (entry.isFile() && entry.name === '_rules.yaml') return true;
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+function listDirsRecursive(base: string, maxDepth: number): Array<{ dir: string; mtime: number; depth: number }> {
+  const out: Array<{ dir: string; mtime: number; depth: number }> = [];
+  const walk = (dir: string, depth: number): void => {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (e.name === '.git' || e.name === 'node_modules') continue;
+      const p = join(dir, e.name);
+      let mtime = 0;
+      try {
+        mtime = statSync(p).mtimeMs;
+      } catch {
+        continue;
+      }
+      out.push({ dir: p, mtime, depth });
+      walk(p, depth + 1);
+    }
+  };
+  walk(base, 1);
+  return out;
+}
+
+/** newest-mtime first; deeper path wins ties (most specific scratch target). */
+function newestFirst(a: { dir: string; mtime: number; depth: number }, b: { dir: string; mtime: number; depth: number }): number {
+  if (b.mtime !== a.mtime) return b.mtime - a.mtime;
+  return b.depth - a.depth;
+}
+
+function scratchRoot(cwd: string): string | null {
+  const tmp = join(cwd, '.tmp');
+  if (!dirExists(tmp)) return null;
+  const dirs = listDirsRecursive(tmp, 3);
+  if (dirs.length === 0) return null;
+  const workspaceLike = dirs.filter(d => looksLikeWorkspace(d.dir));
+  if (workspaceLike.length > 0) {
+    workspaceLike.sort(newestFirst);
+    return workspaceLike[0].dir;
+  }
+  return null;
+}
+
+/** The directory containing spec files.
+ *  1. CANS_ROOT env override.
+ *  2. Walk up from cwd for a `cans/` directory (production contract).
+ *  3. Scratch mode: newest workspace-like dir under <cwd>/.tmp.
+ *  4. null — caller reports "no cans workspace found". */
+export function resolveWorkspaceRoot(): string | null {
+  const env = process.env.CANS_ROOT;
+  if (env && dirExists(env)) return env;
+
+  let dir = process.cwd();
+  for (let i = 0; i < 32; i++) {
+    const cans = join(dir, 'cans');
+    if (dirExists(cans)) return cans;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return scratchRoot(process.cwd());
+}
+
+/** Workspace for commands that may create their target (`new`).
+ *  Falls back to the newest dir under .tmp, then <cwd>/cans. */
+export function resolveWorkspaceOrCreate(): string {
+  const found = resolveWorkspaceRoot();
+  if (found) return found;
+  const tmp = join(process.cwd(), '.tmp');
+  if (dirExists(tmp)) {
+    const dirs = listDirsRecursive(tmp, 3);
+    if (dirs.length > 0) {
+      dirs.sort(newestFirst);
+      return dirs[0].dir;
+    }
+  }
+  return join(process.cwd(), 'cans');
+}
+
+/** Directory in which `cans init` creates the `cans/` workspace.
+ *  1. CANS_ROOT env.
+ *  2. Newest completely-empty dir under <cwd>/.tmp that is not nested inside
+ *     an existing workspace (scratch/sandbox init — never re-inits into
+ *     `cans/_adr`-style empty subdirs of a workspace).
+ *  3. cwd. */
+export function resolveInitTarget(): string {
+  const env = process.env.CANS_ROOT;
+  if (env) return env;
+  const tmp = join(process.cwd(), '.tmp');
+  if (dirExists(tmp)) {
+    const dirs = listDirsRecursive(tmp, 3).filter(d => {
+      // never target a dir that lives inside an existing workspace
+      const rel = relative(tmp, d.dir).split('\\').join('/');
+      if (rel.split('/').includes('cans')) return false;
+      try {
+        return readdirSync(d.dir).length === 0;
+      } catch {
+        return false;
+      }
+    });
+    if (dirs.length > 0) {
+      dirs.sort(newestFirst);
+      return dirs[0].dir;
+    }
+  }
+  return process.cwd();
+}
+
+/** Is cwd inside an existing cans workspace? (init must refuse) */
+export function insideWorkspace(): boolean {
+  let dir = process.cwd();
+  for (let i = 0; i < 32; i++) {
+    if (basename(dir) === 'cans' && dirExists(dir)) return true;
+    const cans = join(dir, 'cans');
+    if (dirExists(cans)) return true;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
+export function toRelative(root: string, p: string): string {
+  const rel = relative(root, p);
+  return rel.split('\\').join('/');
+}
+
+export function isFile(p: string): boolean {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export type { Stats };

package/src/core/index.ts

@@ -0,0 +1,10 @@
+export * from './output';
+export * from './fs';
+export * from './outline';
+export * from './refs';
+export * from './structure';
+export * from './style';
+export * from './redundancy';
+export * from './overflow';
+export * from './rules';
+export * from './token-budget';

package/src/core/outline.ts

@@ -0,0 +1,237 @@
+import type { OutlineNode, BackPointer, RefTarget } from '../types';
+
+const BULLET_RE = /^(\s*)-\s+(.*)$/;
+const CHECKBOX_RE = /^\[( |x|X)\]\s+/;
+const OWNER_RE = /←\s*(@?\S+)/;
+// §11: `see:` parsed via regex — accepts `see:TARGET` (no space), `see: TARGET`, `see TARGET`.
+// The alternation keeps the no-colon form whitespace-required so words like "seed" never match.
+const REF_RE = /see(?::\s*|\s+)([^\s#]+)(?:#([^\s#]+))?/g;
+const REF_BY_RE = /<!--\s*ref-by:\s*(.*?)\s*-->/;
+const FENCE_RE = /^```/;
+
+export interface ParseWarning {
+  line: number;
+  message: string;
+}
+
+/** §45: normalize line terminators at the read/split boundary — CRLF (Windows)
+ *  and lone CR are line terminators just like LF. Root fix so every consumer
+ *  (check/budget/status/export/done) sees the same nodes (QA-08 B5). */
+function normalizeEol(source: string): string {
+  return source.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
+/** Parse markdown bullet outline into an OutlineNode tree.
+ *  Indentation unit: 2 spaces (hardcoded). Tabs rejected.
+ *  Non-bullet lines ignored (prose, headings, blanks are for humans only).
+ *  `warnings` (optional) collects non-fatal parse diagnostics, e.g. odd
+ *  (non-2-multiple) indentation that silently re-parents nodes. */
+export function parseOutline(source: string, file: string, warnings?: ParseWarning[]): OutlineNode[] {
+  const lines = normalizeEol(source).split('\n');
+  for (const line of lines) {
+    if (line.startsWith('\t')) {
+      throw new Error(`${file}: tab indentation rejected (use 2 spaces)`);
+    }
+  }
+
+  const roots: OutlineNode[] = [];
+  const stack: OutlineNode[] = []; // stack[i] = most recent node at indent i
+  let lastNode: OutlineNode | null = null;
+  let fenceOpen = false;
+  let fenceStartLine = 0;
+  let fencePending = false; // saw a fence; mark next close
+  let tableRunOpen = false;
+
+  const makeNode = (text: string, line: number, indent: number): OutlineNode => ({
+    text,
+    line,
+    indent,
+    children: [],
+    file,
+    isTask: false,
+    isDone: false,
+    owner: null,
+    isHumanGate: false,
+    refs: [],
+    hasCodeFence: false,
+    hasTable: false,
+  });
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const lineNo = i + 1;
+
+    // Code fence toggling: fence content is overflow, never bullets.
+    if (FENCE_RE.test(raw.trimEnd()) && raw.trim() !== '```' + '') {
+      // treat any line whose trimmed form starts with ``` as a fence marker
+    }
+    if (raw.trim().startsWith('```')) {
+      if (!fenceOpen) {
+        fenceOpen = true;
+        fenceStartLine = lineNo;
+        fencePending = true;
+      } else {
+        fenceOpen = false;
+        // attach fence flag to last node, or synthesize a node for fence-only files
+        if (lastNode) {
+          lastNode.hasCodeFence = true;
+        } else {
+          const n = makeNode('(code fence)', fenceStartLine, 0);
+          n.hasCodeFence = true;
+          roots.push(n);
+          stack.length = 0;
+          stack.push(n);
+          lastNode = n;
+        }
+      }
+      continue;
+    }
+    if (fenceOpen) continue; // inside fence: ignore
+
+    // Table rows: runs of consecutive `| ... |` lines
+    if (raw.trim().startsWith('|')) {
+      if (!tableRunOpen) {
+        tableRunOpen = true;
+        if (lastNode) {
+          lastNode.hasTable = true;
+        } else {
+          const n = makeNode('(table)', lineNo, 0);
+          n.hasTable = true;
+          roots.push(n);
+          stack.length = 0;
+          stack.push(n);
+          lastNode = n;
+        }
+      }
+      continue;
+    }
+    tableRunOpen = false;
+
+    const m = raw.match(BULLET_RE);
+    if (!m) continue; // prose / heading / blank — humans only
+
+    const leading = m[1];
+    // Warn on non-2-space-aligned indentation — it silently re-parents nodes.
+    if (leading.length % 2 !== 0 && warnings !== undefined) {
+      warnings.push({
+        line: lineNo,
+        message: `odd indentation (${leading.length} space${leading.length === 1 ? '' : 's'}) — nodes may be re-parented unexpectedly; use 2-space multiples`,
+      });
+    }
+    const indent = Math.floor(leading.length / 2);
+    let rest = m[2];
+
+    // strip back-pointer comments from text (metadata, not spec)
+    rest = rest.replace(REF_BY_RE, '').trim();
+
+    // checkbox
+    let isTask = false;
+    let isDone = false;
+    const cb = rest.match(CHECKBOX_RE);
+    if (cb) {
+      isTask = true;
+      isDone = cb[1].toLowerCase() === 'x';
+      rest = rest.slice(cb[0].length).trim();
+    }
+
+    // owner arrow
+    const ownerMatch = rest.match(OWNER_RE);
+    const owner = ownerMatch ? ownerMatch[1] : null;
+
+    // see: references (both "see: X" and "see X" forms)
+    const refs: RefTarget[] = [];
+    let rm: RegExpExecArray | null;
+    REF_RE.lastIndex = 0;
+    while ((rm = REF_RE.exec(rest)) !== null) {
+      refs.push({ raw: rm[0], file: rm[1], anchor: rm[2] ?? null, line: lineNo });
+    }
+
+    const node = makeNode(rest, lineNo, indent);
+    node.isTask = isTask;
+    node.isDone = isDone;
+    node.owner = owner;
+    node.isHumanGate = owner === '@human';
+    node.refs = refs;
+
+    // stack-based attachment
+    if (stack.length === 0) {
+      roots.push(node);
+      stack.push(node);
+    } else {
+      const top = stack[stack.length - 1];
+      if (indent === top.indent) {
+        // sibling of top
+        stack.pop();
+        const parent = stack[stack.length - 1];
+        if (parent) parent.children.push(node);
+        else roots.push(node);
+        stack.push(node);
+      } else if (indent > top.indent) {
+        top.children.push(node);
+        stack.push(node);
+      } else {
+        // shallower: pop until we find the parent level
+        while (stack.length > 1 && stack[stack.length - 1].indent > indent) {
+          stack.pop();
+        }
+        const candidate = stack[stack.length - 1];
+        if (candidate.indent === indent) {
+          stack.pop();
+          const parent = stack[stack.length - 1];
+          if (parent) parent.children.push(node);
+          else roots.push(node);
+          stack.push(node);
+        } else {
+          // indented jump deeper than expected under candidate
+          candidate.children.push(node);
+          stack.push(node);
+        }
+      }
+    }
+    lastNode = node;
+  }
+  void fencePending;
+  return roots;
+}
+
+export function flattenNodes(nodes: OutlineNode[]): OutlineNode[] {
+  const out: OutlineNode[] = [];
+  const walk = (ns: OutlineNode[]): void => {
+    for (const n of ns) {
+      out.push(n);
+      walk(n.children);
+    }
+  };
+  walk(nodes);
+  return out;
+}
+
+export function extractBackPointers(source: string, file: string): BackPointer[] {
+  const out: BackPointer[] = [];
+  const lines = normalizeEol(source).split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(REF_BY_RE);
+    if (!m) continue;
+    const entries = m[1].split(',').map(s => s.trim()).filter(Boolean);
+    for (const e of entries) {
+      out.push({ fromFile: e, fromLine: i + 1, toFile: file, toAnchor: null });
+    }
+  }
+  return out;
+}
+
+export function countNodes(nodes: OutlineNode[]): number {
+  return flattenNodes(nodes).length;
+}
+
+export function maxDepth(nodes: OutlineNode[]): number {
+  let max = 0;
+  const walk = (ns: OutlineNode[]): void => {
+    for (const n of ns) {
+      if (n.indent > max) max = n.indent;
+      walk(n.children);
+    }
+  };
+  walk(nodes);
+  return max;
+}