cans-spec 0.1.2 → 0.3.0

package/src/commands/new.ts

@@ -1,12 +1,13 @@
 import { join, basename } from 'path';
-import type { NewResult } from '../types';
-import { resolveWorkspaceRoot, resolveWorkspaceOrCreate, mkdirp, discoverAdrs, dirExists, isFile } from '../core/fs';
-import { parseArgs, type FlagSpec } from '../core/args';
+import type { NewResult } from '../types.ts';
+import { readText, writeText, dirFromUrl } from '../core/runtime.ts';
+import { resolveWorkspaceRoot, resolveWorkspaceOrCreate, mkdirp, discoverAdrs, dirExists, isFile } from '../core/fs.ts';
+import { parseArgs, type FlagSpec } from '../core/args.ts';
 
-const TEMPLATES_DIR = join(import.meta.dir, '..', '..', 'templates');
+const TEMPLATES_DIR = join(dirFromUrl(import.meta.url), '..', '..', 'templates');
 
 async function readTemplate(name: string): Promise<string> {
-  return await Bun.file(join(TEMPLATES_DIR, name)).text();
+  return await readText(join(TEMPLATES_DIR, name));
 }
 
 /** lowercase → strip double quotes → non-alphanumeric runs → hyphens → trim hyphens.
@@ -58,7 +59,7 @@ async function existingContentGuard(
   change: string,
 ): Promise<NewResult | null> {
   if (!isFile(abs)) return null;
-  const existing = await Bun.file(abs).text();
+  const existing = await readText(abs);
   if (existing === content) {
     return { ok: true, command: 'new', exitCode: 0, change, file };
   }
@@ -116,7 +117,7 @@ export async function run(args: string[]): Promise<NewResult> {
     const file = join('_tasks', `${slug}.md`);
     const guard = await existingContentGuard(join(workspace, file), file, content, slug);
     if (guard !== null) return guard;
-    await Bun.write(join(workspace, file), content);
+    await writeText(join(workspace, file), content);
     return { ok: true, command: 'new', exitCode: 0, change: slug, file };
   }
 
@@ -133,6 +134,6 @@ export async function run(args: string[]): Promise<NewResult> {
   const file = join('_adr', `${NNN}-${slug}.md`);
   const guard = await existingContentGuard(join(workspace, file), file, content, slug);
   if (guard !== null) return guard;
-  await Bun.write(join(workspace, file), content);
+  await writeText(join(workspace, file), content);
   return { ok: true, command: 'new', exitCode: 0, change: slug, file };
 }

package/src/commands/status.ts

@@ -1,12 +1,13 @@
 import { join, basename } from 'path';
 import { readFileSync } from 'fs';
-import type { StatusResult, OutlineNode } from '../types';
+import type { StatusResult, OutlineNode } from '../types.ts';
+import { readText } from '../core/runtime.ts';
 import {
   resolveWorkspaceRoot, discoverSpecFiles, discoverActiveTasks,
   discoverArchivedTasks, discoverAdrs, dirExists,
-} from '../core/fs';
-import { parseOutline, flattenNodes } from '../core/outline';
-import { parseArgs, type FlagSpec } from '../core/args';
+} from '../core/fs.ts';
+import { parseOutline, flattenNodes } from '../core/outline.ts';
+import { parseArgs, type FlagSpec } from '../core/args.ts';
 
 export interface StatusArgs {
   unclaimed: boolean;
@@ -100,7 +101,7 @@ export async function run(args: string[]): Promise<StatusResult> {
   for (const rel of activeTasks) {
     let flat: OutlineNode[] = [];
     try {
-      flat = flattenNodes(parseOutline(await Bun.file(join(workspace, rel)).text(), rel));
+      flat = flattenNodes(parseOutline(await readText(join(workspace, rel)), rel));
     } catch {
       // unparsable task file: contributes nothing but its existence
     }

package/src/converters/index.ts

@@ -1,4 +1,4 @@
-export * from './shared';
-export * from './opml';
-export * from './logseq';
-export * from './obsidian';
+export * from './shared.ts';
+export * from './opml.ts';
+export * from './logseq.ts';
+export * from './obsidian.ts';

package/src/converters/logseq.ts

@@ -1,8 +1,8 @@
-import type { ExternalNode } from '../types';
+import type { ExternalNode } from '../types.ts';
 import {
   convertOwnerMarkers, convertWikiLinks, logseqSlashLinks, parseCheckbox,
   parseIndent, reverseWikiLinks, stripMetadata,
-} from './shared';
+} from './shared.ts';
 
 /** Logseq page → flat ExternalNode list (document order; hierarchy via `indent`).
  *  Drops pure `key:: value` property lines (keys may contain spaces — only `::`

package/src/converters/obsidian.ts

@@ -1,8 +1,8 @@
-import type { ExternalNode } from '../types';
+import type { ExternalNode } from '../types.ts';
 import {
   convertOwnerMarkers, convertWikiLinks, parseCheckbox, parseIndent,
   reverseWikiLinks, stripMetadata,
-} from './shared';
+} from './shared.ts';
 
 /** Remove a leading YAML frontmatter block (`---` fences at very top), fences included. */
 export function stripFrontmatter(source: string): string {

package/src/converters/opml.ts

@@ -1,4 +1,4 @@
-import type { ExternalNode } from '../types';
+import type { ExternalNode } from '../types.ts';
 
 /** Escape the five XML entities. `&` first so output is never double-encoded. */
 export function encodeXmlEntity(s: string): string {

package/src/converters/shared.ts

@@ -1,4 +1,4 @@
-import type { ExternalNode } from '../types';
+import type { ExternalNode } from '../types.ts';
 
 /** Leading whitespace → indent units. 2 spaces per level; each tab counts as 2 spaces. */
 export function parseIndent(raw: string): number {

package/src/core/fs.ts

@@ -1,5 +1,6 @@
 import { statSync, readdirSync, existsSync, mkdirSync, type Stats } from 'fs';
 import { join, relative, dirname, basename } from 'path';
+import { globFiles as runtimeGlobFiles } from './runtime.ts';
 
 const SPEC_FILE_RE = /^\d{2}-.+\.md$/;
 
@@ -26,10 +27,8 @@ export function mkdirp(p: string): void {
 }
 
 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();
+  // Delegated to the runtime shim (issue #12): Bun fast path, node:fs fallback.
+  return runtimeGlobFiles(dir, pattern);
 }
 
 /** Spec files: root-level *.md (excluding _-prefixed, AGENTS.md and other tool

package/src/core/index.ts

@@ -1,10 +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';
+export * from './output.ts';
+export * from './fs.ts';
+export * from './outline.ts';
+export * from './refs.ts';
+export * from './structure.ts';
+export * from './style.ts';
+export * from './redundancy.ts';
+export * from './overflow.ts';
+export * from './rules.ts';
+export * from './token-budget.ts';

package/src/core/outline.ts

@@ -1,4 +1,4 @@
-import type { OutlineNode, BackPointer, RefTarget } from '../types';
+import type { OutlineNode, BackPointer, RefTarget } from '../types.ts';
 
 const BULLET_RE = /^(\s*)-\s+(.*)$/;
 const CHECKBOX_RE = /^\[( |x|X)\]\s+/;
@@ -55,6 +55,9 @@ export function parseOutline(source: string, file: string, warnings?: ParseWarni
     refs: [],
     hasCodeFence: false,
     hasTable: false,
+    // Issue #8: real bullets are never synthetic; the two placeholder
+    // synthesis sites below flip this to true after makeNode.
+    synthetic: false,
   });
 
   for (let i = 0; i < lines.length; i++) {
@@ -78,6 +81,7 @@ export function parseOutline(source: string, file: string, warnings?: ParseWarni
         } else {
           const n = makeNode('(code fence)', fenceStartLine, 0);
           n.hasCodeFence = true;
+          n.synthetic = true; // issue #8: placeholder, not user content
           roots.push(n);
           stack.length = 0;
           stack.push(n);
@@ -97,6 +101,7 @@ export function parseOutline(source: string, file: string, warnings?: ParseWarni
         } else {
           const n = makeNode('(table)', lineNo, 0);
           n.hasTable = true;
+          n.synthetic = true; // issue #8: placeholder, not user content
           roots.push(n);
           stack.length = 0;
           stack.push(n);
@@ -170,20 +175,29 @@ export function parseOutline(source: string, file: string, warnings?: ParseWarni
         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) {
+        // shallower: pop until we find the parent level — all the way to an
+        // empty stack, not just down to stack[0] (issue #7). The stack bottom
+        // is only a real parent when the file's first bullet sits at column
+        // 0; when it opens indented (e.g. under a `#` heading) its indent
+        // must not swallow bullets that dedent past it, or the whole tree
+        // silently re-parents under that first node.
+        while (stack.length > 0 && stack[stack.length - 1].indent > indent) {
           stack.pop();
         }
-        const candidate = stack[stack.length - 1];
-        if (candidate.indent === indent) {
+        if (stack.length === 0) {
+          // dedented past every open node: a root sibling
+          roots.push(node);
+          stack.push(node);
+        } else if (stack[stack.length - 1].indent === indent) {
+          // sibling of the deepest open node at this level
           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);
+          // indented jump deeper than expected under that node
+          stack[stack.length - 1].children.push(node);
           stack.push(node);
         }
       }
@@ -194,6 +208,12 @@ export function parseOutline(source: string, file: string, warnings?: ParseWarni
   return roots;
 }
 
+/** Issue #8: true only for parser-created placeholder nodes ("(table)" /
+ *  "(code fence)") representing a leading table/fence — never user content. */
+export function isSyntheticNode(n: OutlineNode): boolean {
+  return n.synthetic === true;
+}
+
 export function flattenNodes(nodes: OutlineNode[]): OutlineNode[] {
   const out: OutlineNode[] = [];
   const walk = (ns: OutlineNode[]): void => {
@@ -209,8 +229,18 @@ export function flattenNodes(nodes: OutlineNode[]): OutlineNode[] {
 export function extractBackPointers(source: string, file: string): BackPointer[] {
   const out: BackPointer[] = [];
   const lines = normalizeEol(source).split('\n');
+  // Issue #6: fence awareness — a `<!-- ref-by: ... -->` quoted inside a fenced
+  // example is documentation, not a real back-pointer. Same toggle rule as
+  // parseOutline (trimmed line starts with ```); the marker line itself is
+  // fence infrastructure and never carries a counted comment either.
+  let fenceOpen = false;
   for (let i = 0; i < lines.length; i++) {
-    const m = lines[i].match(REF_BY_RE);
+    if (FENCE_RE.test(lines[i]!.trim())) {
+      fenceOpen = !fenceOpen;
+      continue;
+    }
+    if (fenceOpen) continue;
+    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) {
@@ -220,6 +250,14 @@ export function extractBackPointers(source: string, file: string): BackPointer[]
   return out;
 }
 
+/** Flattened tree WITHOUT synthetic placeholder nodes — the view every
+ *  node-count and content-comparison consumer should use (issue #8).
+ *  flattenNodes itself is unchanged: the tree shape keeps the placeholders
+ *  (they carry hasTable/hasCodeFence for the overflow engine). */
+export function realNodes(nodes: OutlineNode[]): OutlineNode[] {
+  return flattenNodes(nodes).filter(n => !isSyntheticNode(n));
+}
+
 export function countNodes(nodes: OutlineNode[]): number {
   return flattenNodes(nodes).length;
 }

package/src/core/output.ts

@@ -1,7 +1,7 @@
 import type {
   CommandResult, CheckResult, Issue, InitResult, NewResult, DoneResult, StatusResult,
   BudgetReadResult, BudgetWriteResult, ImportResult, ExportResult, VersionResult,
-} from '../types';
+} from '../types.ts';
 
 /** Single emission point. Commands never console.log or process.exit directly.
  *  `refsOnly` (check only, §22/§36): human output is scoped to the References

package/src/core/overflow.ts

@@ -1,5 +1,5 @@
-import type { OutlineNode, Issue, OverflowRules } from '../types';
-import { flattenNodes } from './outline';
+import type { OutlineNode, Issue, OverflowRules } from '../types.ts';
+import { flattenNodes } from './outline.ts';
 
 /** Overflow checks: code fences, tables, over-long nodes. All errors.
  *  §18: `force_file_for` lists the content categories forced into files —

package/src/core/redundancy.ts

@@ -1,5 +1,5 @@
-import type { OutlineNode, Issue, RedundancyRules } from '../types';
-import { flattenNodes } from './outline';
+import type { OutlineNode, Issue, RedundancyRules } from '../types.ts';
+import { flattenNodes, isSyntheticNode } from './outline.ts';
 
 interface NodeRef {
   text: string;
@@ -133,21 +133,63 @@ export function phraseOverlap(
   return issues;
 }
 
+/** Light English suffixes for the inflection check (issue #3), longest first —
+ *  stripped iteratively from the end so "carries" → "carri" (→ i↔y → "carry"). */
+const INFLECTION_SUFFIXES = ['ing', 'ers', 'er', 'ed', 'es', 'ly', 's'];
+
+/** Reduce a word to a rough stem by iteratively stripping common English
+ *  suffixes, then a trailing `e`, folding a trailing `i` onto `y` (so
+ *  deny/denied → deny, approve/approved → approv). Deliberately NOT a real
+ *  stemmer — only good enough to recognize pure suffix inflections. */
+function lightStem(word: string): string {
+  let w = word;
+  for (;;) {
+    const suffix = INFLECTION_SUFFIXES.find(s => w.length > s.length && w.endsWith(s));
+    if (suffix === undefined) break;
+    w = w.slice(0, w.length - suffix.length);
+  }
+  if (w.endsWith('i')) w = `${w.slice(0, -1)}y`;
+  if (w.endsWith('e')) w = w.slice(0, -1);
+  return w;
+}
+
+/** Issue #3: is `a` a pure suffix-inflection of `b` (or vice versa)? Both words
+ *  are reduced with lightStem; equal stems — or a stem equal to the other word's
+ *  unstemmed form — mean the pair differs only by an English inflection
+ *  (approve/approved, session/sessions, deny/denied), not by a typo. Stems
+ *  shorter than 3 chars are treated as unsafe and the pair is NOT skipped
+ *  (e.g. sing/singe stays a typo candidate). Genuine near-misses with no suffix
+ *  relation (flavour/flavor, table/tabble) keep different stems → still flagged. */
+export function isInflectionOf(a: string, b: string): boolean {
+  const sa = lightStem(a);
+  const sb = lightStem(b);
+  if (sa.length < 3 || sb.length < 3) return false;
+  return sa === sb || sa === b || sb === a;
+}
+
 /** Layer 3 — near-miss word forms (Levenshtein <= 2, both words > 4 chars) → possible typo.
  *  §13: "NOT ALREADY SYNONYM-MATCHED" — words are normalized with the rules'
  *  synonym groups first, so members of the same group collapse to one word and
- *  never pair up as typos. */
+ *  never pair up as typos. Issue #3: the layer now applies the SAME collection
+ *  filter as the other layers — the configured `redundancy.stopwords` and the
+ *  §8/§13 ref-syntax tokens (`see`, `md`) are never collected — and skips
+ *  candidate pairs that are pure suffix inflections of each other
+ *  (isInflectionOf) before the Levenshtein comparison, so English inflections
+ *  (approved/approve, sessions/session) are no longer reported as typos. */
 export function fuzzyDistance(
   nodes: NodeRef[],
   rules?: RedundancyRules,
 ): Issue[] {
   const synonyms = rules ? rules.synonyms : [];
+  const stopwords = rules ? rules.stopwords : [];
   const words: NodeRef[] = [];
   const seen = new Set<string>();
   for (const node of nodes) {
     for (const raw of tokenize(node.text)) {
       const w = normalizeWord(raw, synonyms);
       if (w.length === 0 || seen.has(w)) continue;
+      if (REF_SYNTAX_TOKENS.has(w)) continue;
+      if (stopwords.includes(w)) continue;
       seen.add(w);
       words.push({ text: w, file: node.file, line: node.line });
     }
@@ -159,6 +201,7 @@ export function fuzzyDistance(
       const b = words[j];
       if (a.text.length <= 4 || b.text.length <= 4) continue;
       if (Math.abs(a.text.length - b.text.length) > 2) continue;
+      if (isInflectionOf(a.text, b.text)) continue;
       const d = levenshtein(a.text, b.text);
       if (d <= 2) {
         issues.push({
@@ -208,6 +251,10 @@ export function crossFileCanonicality(
   const concepts = new Map<string, { files: Set<string>; first: NodeRef }>();
   for (const [key, nodes] of allFiles) {
     for (const node of flattenNodes(nodes)) {
+      // Issue #8: synthetic "(table)"/"(code fence)" placeholders are not
+      // concepts — comparing them across files fabricated "canonical home"
+      // warnings with nonsense advice.
+      if (isSyntheticNode(node)) continue;
       if (node.indent > 1) continue;
       const text = node.text.trim().toLowerCase();
       if (text.length === 0) continue;
@@ -240,7 +287,9 @@ export function crossFileCanonicality(
 }
 
 /** All four redundancy layers over every loaded spec node.
- *  `duplicateHomeCheck` (§18 references.duplicate_home_check) gates layer 4. */
+ *  `duplicateHomeCheck` (§18 references.duplicate_home_check) gates layer 4.
+ *  Issue #3: `redundancy.fuzzy` (§18 delete-key semantics: deleted → false)
+ *  gates layer 3 independently of `enabled`, which still covers all layers. */
 export function checkRedundancy(
   allFiles: Map<string, OutlineNode[]>,
   rules: RedundancyRules,
@@ -249,13 +298,18 @@ export function checkRedundancy(
   const nodes: NodeRef[] = [];
   for (const [file, tree] of allFiles) {
     for (const node of flattenNodes(tree)) {
+      // Issue #8: synthetic "(table)"/"(code fence)" placeholders are not
+      // content — excluded from all three text-comparison layers (they made
+      // any two table-opening files 100%-overlapping and inflated the
+      // "table"/"code"/"fence" word-frequency counts).
+      if (isSyntheticNode(node)) continue;
       nodes.push({ text: node.text, file, line: node.line });
     }
   }
   return [
     ...wordFrequency(nodes, rules),
     ...phraseOverlap(nodes, rules.phrase_overlap_threshold, rules),
-    ...fuzzyDistance(nodes, rules),
+    ...(rules.fuzzy !== false ? fuzzyDistance(nodes, rules) : []),
     ...(duplicateHomeCheck ? crossFileCanonicality(allFiles, rules.cross_file_threshold) : []),
   ];
 }