cans-spec 0.1.2 → 0.3.0

package/src/core/style.ts

@@ -1,6 +1,23 @@
-import type { OutlineNode, Issue, StyleRules } from '../types';
+import type { OutlineNode, Issue, StyleRules } from '../types.ts';
+import { isSyntheticNode } from './outline.ts';
 
-/** Style checks: shared-prefix nesting hint + unnecessary-nesting collapse hint.
+/** Style checks: shared-prefix nesting hint + unnecessary-nesting collapse hint,
+ *  modulated by `style.prefer` (issue #2 — the key was parsed and reconciled but
+ *  never read, so `prefer: nested` still advised "Collapse to sibling style.").
+ *
+ *  Prefer semantics:
+ *    - `prefer: 'sibling'` — the author prefers flat sibling lists: the
+ *      shared-prefix "Group under nested style." hint is suppressed (it argues
+ *      against the declared preference); the collapse-to-sibling hint still
+ *      fires (it agrees with it).
+ *    - `prefer: 'nested'` — the author prefers grouped outlines: the
+ *      "Collapse to sibling style." hint is suppressed; the shared-prefix
+ *      grouping hint still fires.
+ *    - `prefer: null` (key deleted, §18) — NO prefer-driven modulation: both
+ *      base hints fire exactly as they did before the prefer wiring existed.
+ *      "Deleted `prefer` disables prefer-driven style guidance" therefore means
+ *      the prefer-driven MODULATION is off, not that the base guidance is off.
+ *
  *  SEVERITY NOTE (arbitration, same class as the refs-severity decision): §14/§36
  *  show ✗ for style flags, but the frozen §35/§18 fixtures (flat-project,
  *  folder-project, init templates) structurally trigger the ≤N-leaf rule and the
@@ -8,8 +25,9 @@ import type { OutlineNode, Issue, StyleRules } from '../types';
  *  findings stay `warning`-level. Changing test fixtures is out of bounds
  *  (test/ is frozen).
  *  §18 delete-key semantics: a style rule whose key is null/false no longer
- *  fires (deleted force_nested_above / force_sibling_below / prefer or
- *  shared_prefix_detection: false skip their rules entirely). */
+ *  fires — deleted force_nested_above / force_sibling_below or
+ *  shared_prefix_detection: false skip their rules entirely (deleted `prefer`
+ *  is the modulation-off case documented above; it skips nothing). */
 export function checkStyle(
   nodes: OutlineNode[],
   file: string,
@@ -21,49 +39,64 @@ export function checkStyle(
     for (const node of list) {
       const children = node.children;
 
-      const nestedAbove = rules.force_nested_above;
-      if (rules.shared_prefix_detection && nestedAbove !== null && children.length >= nestedAbove) {
-        const groups = new Map<string, number>();
-        for (const child of children) {
-          const word = child.text.split(/\s+/)[0] ?? '';
-          if (word === '') continue;
-          groups.set(word, (groups.get(word) ?? 0) + 1);
-        }
-        for (const [word, size] of groups) {
-          if (size >= nestedAbove) {
-            issues.push({
-              file,
-              line: node.line,
-              level: 'warning',
-              category: 'style',
-              message: `${size} siblings share prefix "${word}". Group under nested style.`,
-            });
+      // Issue #8: synthetic "(table)"/"(code fence)" placeholders are not user
+      // structure — never flagged themselves (their children, if any, still
+      // are: the walk recurses below regardless).
+      if (!isSyntheticNode(node)) {
+        const nestedAbove = rules.force_nested_above;
+        // prefer: 'sibling' declares a flat-list preference — the grouping hint
+        // contradicts it and is suppressed ('nested'/null keep it firing).
+        if (
+          rules.shared_prefix_detection &&
+          rules.prefer !== 'sibling' &&
+          nestedAbove !== null &&
+          children.length >= nestedAbove
+        ) {
+          const groups = new Map<string, number>();
+          for (const child of children) {
+            const word = child.text.split(/\s+/)[0] ?? '';
+            if (word === '') continue;
+            groups.set(word, (groups.get(word) ?? 0) + 1);
+          }
+          for (const [word, size] of groups) {
+            if (size >= nestedAbove) {
+              issues.push({
+                file,
+                line: node.line,
+                level: 'warning',
+                category: 'style',
+                message: `${size} siblings share prefix "${word}". Group under nested style.`,
+              });
+            }
           }
         }
-      }
 
-      // §14: "Parent with ≤ force_sibling_below leaf children → collapse to
-      // sibling style." `≤` semantics (exactly N is flagged). The file root is
-      // exempt — a root concept with few subtopics is the normal spec shape,
-      // not unnecessary nesting. A single child is reported by the structure
-      // engine ("exactly 1 child"); don't double-report it here.
-      const siblingBelow = rules.force_sibling_below;
-      if (
-        siblingBelow !== null &&
-        node.indent > 0 &&
-        children.length >= 2 &&
-        children.length <= siblingBelow &&
-        children.every((c) => c.children.length === 0)
-      ) {
-        issues.push({
-          file,
-          line: node.line,
-          level: 'warning',
-          category: 'style',
-          // QA-03 F17 pluralization contract (unreachable for 1 — the ≥2 guard
-          // above plus the structure engine owns the 1-child case).
-          message: `"${node.text}" has ${children.length} ${children.length === 1 ? 'child' : 'children'}. Collapse to sibling style.`,
-        });
+        // §14: "Parent with ≤ force_sibling_below leaf children → collapse to
+        // sibling style." `≤` semantics (exactly N is flagged). The file root is
+        // exempt — a root concept with few subtopics is the normal spec shape,
+        // not unnecessary nesting. A single child is reported by the structure
+        // engine ("exactly 1 child"); don't double-report it here.
+        const siblingBelow = rules.force_sibling_below;
+        // prefer: 'nested' declares a grouped-outline preference — the collapse
+        // hint contradicts it and is suppressed ('sibling'/null keep it firing).
+        if (
+          siblingBelow !== null &&
+          rules.prefer !== 'nested' &&
+          node.indent > 0 &&
+          children.length >= 2 &&
+          children.length <= siblingBelow &&
+          children.every((c) => c.children.length === 0)
+        ) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'warning',
+            category: 'style',
+            // QA-03 F17 pluralization contract (unreachable for 1 — the ≥2 guard
+            // above plus the structure engine owns the 1-child case).
+            message: `"${node.text}" has ${children.length} ${children.length === 1 ? 'child' : 'children'}. Collapse to sibling style.`,
+          });
+        }
       }
 
       walk(children);

package/src/core/token-budget.ts

@@ -3,9 +3,9 @@ import { basename, relative } from 'path';
 import type {
   OutlineNode, BackPointer, TokenBudgetRules,
   BudgetReadPlanItem, BudgetReadResult, BudgetWriteResult,
-} from '../types';
-import { flattenNodes, parseOutline } from './outline';
-import { targetMatchesKey } from './refs';
+} from '../types.ts';
+import { flattenNodes, parseOutline, isSyntheticNode } from './outline.ts';
+import { targetMatchesKey } from './refs.ts';
 
 export function estimateTokens(text: string, charsPerToken: number): number {
   return Math.ceil(text.length / charsPerToken);
@@ -19,7 +19,10 @@ function relPath(file: string): string {
 }
 
 function serializedNodeText(nodes: OutlineNode[]): string {
-  return flattenNodes(nodes).map(n => n.text).join('\n');
+  // Issue #8: synthetic "(table)"/"(code fence)" placeholders are not content —
+  // including them inflated every token estimate for files opening with a
+  // table/fence.
+  return flattenNodes(nodes).filter(n => !isSyntheticNode(n)).map(n => n.text).join('\n');
 }
 
 /** Token estimate for a workspace key (loaded nodes) or a raw file path (content read). */
@@ -53,6 +56,8 @@ export function findCanonicalHome(
   const candidates: Array<{ file: string; node: OutlineNode }> = [];
   for (const [file, nodes] of allFiles) {
     for (const node of flattenNodes(nodes)) {
+      // Issue #8: a synthetic placeholder must never be the canonical home.
+      if (isSyntheticNode(node)) continue;
       if (node.text.toLowerCase().includes(lc)) candidates.push({ file, node });
     }
   }

package/src/types.ts

@@ -20,6 +20,13 @@ export interface OutlineNode {
   refs: RefTarget[];
   hasCodeFence: boolean;
   hasTable: boolean;
+  /** Issue #8: true ONLY for parser-created placeholder nodes (text "(table)"
+   *  or "(code fence)") that represent a table/fence appearing BEFORE the
+   *  first bullet of a file. They carry the hasTable/hasCodeFence signal but
+   *  are not user content — consumers that count nodes or compare node text
+   *  as content must exclude them (isSyntheticNode). Never set on nodes
+   *  parsed from real bullets. */
+  synthetic?: boolean;
 }
 
 export interface BackPointer {
@@ -63,7 +70,9 @@ export interface StructureRules {
 }
 
 export interface StyleRules {
-  /** Deleted `prefer` disables prefer-driven style guidance (§18). */
+  /** Style-guide selector: `sibling` suppresses the nested-grouping hint,
+   *  `nested` suppresses the sibling-collapse hint; null (deleted, §18) → no
+   *  prefer-driven modulation — both base style hints fire unchanged. */
   prefer: 'sibling' | 'nested' | null;
   force_nested_above: number | null;
   force_sibling_below: number | null;
@@ -90,6 +99,8 @@ export interface RedundancyRules {
   word_frequency_threshold: number | null;
   phrase_overlap_threshold: number | null;
   cross_file_threshold: number | null;
+  /** Layer 3 switch: deleted → false (§18 delete-key semantics). */
+  fuzzy: boolean;
   /** Parameters (not checks): keep their defaults when deleted (§18). */
   stopwords: string[];
   synonyms: string[][];

package/templates/_rules.yaml

@@ -27,6 +27,7 @@ redundancy:
   word_frequency_threshold: 4
   phrase_overlap_threshold: 0.7
   cross_file_threshold: 2
+  fuzzy: true
   stopwords: [the, a, an, of, to, in, for, and, or, with, must, shall, requires]
   synonyms:
     - [postgres, postgresql, pg]