feat(diagnostics): resolve revision-scoped text selectors

.github/workflows/writing-diagnostics-projection-tdd.yml

@@ -0,0 +1,126 @@
+name: Writing Diagnostics Projection TDD
+
+on:
+  push:
+    branches:
+      - feat/writing-diagnostics-projection
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: writing-diagnostics-projection-tdd-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  focused-projection:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 35
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+      - uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Collect forward and inverse projection coverage
+        id: focused_coverage
+        continue-on-error: true
+        run: >-
+          pnpm exec vitest run
+          src/writingDiagnosticProjection.test.ts
+          src/writingDiagnosticProjectionBoundary.test.ts
+          src/writingDiagnosticProjectionCoverage.test.ts
+          src/textPositionSelectorEvidenceBoundary.test.ts
+          src/writingDiagnosticProjectionExports.test.ts
+          --coverage
+          --coverage.include=src/graphemeBoundary.ts
+          --coverage.include=src/textPositionSelectorEvidence.ts
+          --coverage.include=src/writingDiagnosticProjection.ts
+          --coverage.reporter=text
+          --coverage.reporter=json
+          --coverage.reporter=json-summary
+      - name: Report and enforce exact projection coverage
+        run: |
+          node <<'NODE'
+          const { readFileSync } = require('node:fs');
+          const coverage = JSON.parse(readFileSync('coverage/coverage-final.json', 'utf8'));
+          const requiredSuffixes = [
+            '/src/graphemeBoundary.ts',
+            '/src/textPositionSelectorEvidence.ts',
+            '/src/writingDiagnosticProjection.ts',
+          ];
+          let failed = process.env.FOCUSED_COVERAGE_OUTCOME !== 'success';
+
+          for (const suffix of requiredSuffixes) {
+            const entry = Object.entries(coverage).find(([path]) => path.endsWith(suffix));
+            const displayPath = suffix.slice(1);
+            if (!entry) {
+              console.error(`::error file=${displayPath},line=1::Focused coverage record is missing.`);
+              failed = true;
+              continue;
+            }
+            const [, fileCoverage] = entry;
+            const missingStatementLines = [...new Set(
+              Object.entries(fileCoverage.s)
+                .filter(([, count]) => count === 0)
+                .map(([id]) => fileCoverage.statementMap[id].start.line),
+            )].sort((a, b) => a - b);
+            const missingFunctionLines = [...new Set(
+              Object.entries(fileCoverage.f)
+                .filter(([, count]) => count === 0)
+                .map(([id]) => fileCoverage.fnMap[id].decl.start.line),
+            )].sort((a, b) => a - b);
+            const missingBranches = [];
+            for (const [id, counts] of Object.entries(fileCoverage.b)) {
+              counts.forEach((count, index) => {
+                if (count === 0) {
+                  const branch = fileCoverage.branchMap[id];
+                  const location = branch.locations?.[index] ?? branch.loc;
+                  missingBranches.push(`${location.start.line}:${index}`);
+                }
+              });
+            }
+            const statementTotal = Object.keys(fileCoverage.s).length;
+            const statementCovered = Object.values(fileCoverage.s).filter((count) => count > 0).length;
+            const functionTotal = Object.keys(fileCoverage.f).length;
+            const functionCovered = Object.values(fileCoverage.f).filter((count) => count > 0).length;
+            const branchCounts = Object.values(fileCoverage.b).flat();
+            const branchTotal = branchCounts.length;
+            const branchCovered = branchCounts.filter((count) => count > 0).length;
+            console.log(
+              `::notice file=${displayPath},line=1::Statements ${statementCovered}/${statementTotal}; ` +
+              `functions ${functionCovered}/${functionTotal}; branches ${branchCovered}/${branchTotal}.`,
+            );
+            if (missingStatementLines.length || missingFunctionLines.length || missingBranches.length) {
+              console.error(
+                `::error file=${displayPath},line=1::` +
+                `Missing statement lines: ${missingStatementLines.join(', ') || 'none'}; ` +
+                `missing function lines: ${missingFunctionLines.join(', ') || 'none'}; ` +
+                `missing branches line:index: ${missingBranches.join(', ') || 'none'}.`,
+              );
+              failed = true;
+            }
+          }
+          if (failed) process.exit(1);
+          NODE
+        env:
+          FOCUSED_COVERAGE_OUTCOME: ${{ steps.focused_coverage.outcome }}
+      - name: Typecheck inverse projection contracts
+        run: pnpm typecheck
+      - name: Run complete production coverage gate
+        run: pnpm coverage
+      - name: Build all package entrypoints
+        run: pnpm build
+      - name: Verify isolated packed-package consumers
+        run: pnpm verify:package
+      - name: Build the demonstration application
+        run: pnpm build:demo

scripts/verify-text-position-selector-subpath-package.mjs

@@ -123,12 +123,20 @@ import {
   TEXT_POSITION_PROJECTION_ID,
   TEXT_POSITION_PROJECTION_VERSION,
   TextPositionSelectorEvidenceError,
+  WritingDiagnosticProjectionError,
+  buildTextProjectionMap,
   createTextPositionSelector,
+  resolveTextPositionSelector,
 } from '${packageJson.name}/text-position-selector';
 assert.equal(TEXT_POSITION_PROJECTION_ID, 'inkspan-prosemirror-text');
 assert.equal(TEXT_POSITION_PROJECTION_VERSION, 1);
 assert.equal(typeof TextPositionSelectorEvidenceError, 'function');
+assert.equal(typeof WritingDiagnosticProjectionError, 'function');
+assert.equal(typeof buildTextProjectionMap, 'function');
 assert.equal(typeof createTextPositionSelector, 'function');
+assert.equal(typeof resolveTextPositionSelector, 'function');
+const failure = new WritingDiagnosticProjectionError('selector');
+assert.equal(failure.code, 'selector');
 `,
     'utf8',
   );
@@ -141,7 +149,12 @@ const selector = require('${packageJson.name}/text-position-selector');
 assert.equal(selector.TEXT_POSITION_PROJECTION_ID, 'inkspan-prosemirror-text');
 assert.equal(selector.TEXT_POSITION_PROJECTION_VERSION, 1);
 assert.equal(typeof selector.TextPositionSelectorEvidenceError, 'function');
+assert.equal(typeof selector.WritingDiagnosticProjectionError, 'function');
+assert.equal(typeof selector.buildTextProjectionMap, 'function');
 assert.equal(typeof selector.createTextPositionSelector, 'function');
+assert.equal(typeof selector.resolveTextPositionSelector, 'function');
+const failure = new selector.WritingDiagnosticProjectionError('ambiguous_boundary');
+assert.equal(failure.code, 'ambiguous_boundary');
 `,
     'utf8',
   );
@@ -160,26 +173,40 @@ function verifyDeclarationConsumer() {
   TEXT_POSITION_PROJECTION_ID,
   TEXT_POSITION_PROJECTION_VERSION,
   TextPositionSelectorEvidenceError,
+  WritingDiagnosticProjectionError,
+  buildTextProjectionMap,
   createTextPositionSelector,
+  resolveTextPositionSelector,
   type CwlEditorTextPositionSelector,
   type CwlEditorTextProjectionIdentity,
+  type CwlWritingDiagnosticTextProjectionMap,
   type TextPositionSelectorEvidenceErrorCode,
+  type WritingDiagnosticProjectionErrorCode,
 } from '${packageJson.name}/text-position-selector';
 import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
 import type { Selection } from '@tiptap/pm/state';
 declare const documentNode: ProseMirrorNode;
 declare const selection: Selection;
-const result = createTextPositionSelector(documentNode, selection);
-const selector: CwlEditorTextPositionSelector = result.selector;
-const projection: CwlEditorTextProjectionIdentity = result.textProjection;
-const code: TextPositionSelectorEvidenceErrorCode = 'segmenter_unavailable';
-const failure = new TextPositionSelectorEvidenceError(code);
+const forward = createTextPositionSelector(documentNode, selection);
+const selector: CwlEditorTextPositionSelector = forward.selector;
+const projection: CwlEditorTextProjectionIdentity = forward.textProjection;
+const map: CwlWritingDiagnosticTextProjectionMap = buildTextProjectionMap(documentNode);
+const resolved = resolveTextPositionSelector(documentNode, selector, projection);
+const evidenceCode: TextPositionSelectorEvidenceErrorCode = 'segmenter_unavailable';
+const projectionCode: WritingDiagnosticProjectionErrorCode = 'ambiguous_boundary';
+const evidenceFailure = new TextPositionSelectorEvidenceError(evidenceCode);
+const projectionFailure = new WritingDiagnosticProjectionError(projectionCode);
 void [
   selector.start,
   selector.end,
   projection.id === TEXT_POSITION_PROJECTION_ID,
   projection.version === TEXT_POSITION_PROJECTION_VERSION,
-  failure.code,
+  map.text,
+  map.boundaryPositions.length,
+  resolved.from,
+  resolved.to,
+  evidenceFailure.code,
+  projectionFailure.code,
 ];
 `,
     'utf8',

src/graphemeBoundary.ts

@@ -0,0 +1,52 @@
+/** Internal result of checking one UTF-16 code-unit offset against grapheme boundaries. */
+export type GraphemeBoundaryState = 'boundary' | 'inside_grapheme' | 'unavailable';
+
+interface GraphemeSegment {
+  readonly index: number;
+}
+
+interface GraphemeSegmenter {
+  segment(input: string): Iterable<GraphemeSegment>;
+}
+
+interface GraphemeSegmenterConstructor {
+  new (
+    locales?: string | readonly string[],
+    options?: { readonly granularity: 'grapheme' },
+  ): GraphemeSegmenter;
+}
+
+/**
+ * Classify one UTF-16 code-unit offset using the runtime's Unicode grapheme segmenter.
+ *
+ * Callers retain authority over their public error type. Any unavailable,
+ * replaced, or throwing runtime segmenter produces one stable unsupported state
+ * instead of leaking host exceptions across the selector boundary.
+ */
+export function classifyGraphemeBoundary(
+  text: string,
+  codeUnitOffset: number,
+): GraphemeBoundaryState {
+  try {
+    const Segmenter = (
+      Intl as unknown as { Segmenter?: GraphemeSegmenterConstructor }
+    ).Segmenter;
+    if (typeof Segmenter !== 'function') {
+      return 'unavailable';
+    }
+
+    if (codeUnitOffset === 0 || codeUnitOffset === text.length) {
+      return 'boundary';
+    }
+    for (const segment of new Segmenter(undefined, {
+      granularity: 'grapheme',
+    }).segment(text)) {
+      if (segment.index === codeUnitOffset) {
+        return 'boundary';
+      }
+    }
+    return 'inside_grapheme';
+  } catch {
+    return 'unavailable';
+  }
+}

src/index.ts

@@ -49,6 +49,15 @@ export type {
   CwlEditorTextProjectionIdentity,
   TextPositionSelectorEvidenceErrorCode,
 } from './textPositionSelectorEvidence.js';
+export {
+  WritingDiagnosticProjectionError,
+  buildTextProjectionMap,
+  resolveTextPositionSelector,
+} from './writingDiagnosticProjection.js';
+export type {
+  CwlWritingDiagnosticTextProjectionMap,
+  WritingDiagnosticProjectionErrorCode,
+} from './writingDiagnosticProjection.js';
 
 // Host-owned, revision-scoped writing diagnostic contract.
 export {

src/text-position-selector/index.ts

@@ -1,9 +1,9 @@
 /**
  * React-free W3C text-position selector projection surface.
  *
- * This subpath exposes only deterministic projection primitives. Interactive
- * editor-handle capture and exact revision binding remain on the root Inkspan
- * editor contract.
+ * This subpath exposes deterministic forward and inverse projection primitives.
+ * Interactive editor-handle capture and exact revision binding remain on the
+ * root Inkspan editor contract.
  */
 export {
   TEXT_POSITION_PROJECTION_ID,
@@ -16,3 +16,12 @@ export type {
   CwlEditorTextProjectionIdentity,
   TextPositionSelectorEvidenceErrorCode,
 } from '../textPositionSelectorEvidence.js';
+export {
+  WritingDiagnosticProjectionError,
+  buildTextProjectionMap,
+  resolveTextPositionSelector,
+} from '../writingDiagnosticProjection.js';
+export type {
+  CwlWritingDiagnosticTextProjectionMap,
+  WritingDiagnosticProjectionErrorCode,
+} from '../writingDiagnosticProjection.js';

src/textPositionSelectorEvidence.ts

@@ -1,6 +1,7 @@
 import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
 import type { Selection } from '@tiptap/pm/state';
 import type { CwlEditorDocumentRevision } from './documentEnvelopeRevision.js';
+import { classifyGraphemeBoundary } from './graphemeBoundary.js';
 
 /** Stable identity of Inkspan's first W3C-compatible logical text projection. */
 export const TEXT_POSITION_PROJECTION_ID = 'inkspan-prosemirror-text' as const;
@@ -60,21 +61,6 @@
   }
 }
 
-interface GraphemeSegment {
-  readonly index: number;
-}
-
-interface GraphemeSegmenter {
-  segment(input: string): Iterable<GraphemeSegment>;
-}
-
-interface GraphemeSegmenterConstructor {
-  new (
-    locales?: string | readonly string[],
-    options?: { readonly granularity: 'grapheme' },
-  ): GraphemeSegmenter;
-}
-
 /** Project a prefix of one ProseMirror document under the versioned v1 rules. */
 function projectDocumentPrefix(documentNode: ProseMirrorNode, to: number): string {
   return documentNode.textBetween(0, to, BLOCK_SEPARATOR, LEAF_TEXT);
@@ -87,20 +73,11 @@
 
 /** Require a position to coincide with a Unicode grapheme-cluster boundary. */
 function assertGraphemeBoundary(text: string, codeUnitOffset: number): void {
-  const Segmenter = (
-    Intl as unknown as { Segmenter?: GraphemeSegmenterConstructor }
-  ).Segmenter;
-  if (typeof Segmenter !== 'function') {
+  const boundaryState = classifyGraphemeBoundary(text, codeUnitOffset);
+  if (boundaryState === 'unavailable') {
     throw new TextPositionSelectorEvidenceError('segmenter_unavailable');
   }
-
-  const boundaries = new Set<number>([0, text.length]);
-  for (const segment of new Segmenter(undefined, { granularity: 'grapheme' }).segment(
-    text,
-  )) {
-    boundaries.add(segment.index);
-  }
-  if (!boundaries.has(codeUnitOffset)) {
+  if (boundaryState !== 'boundary') {
     throw new TextPositionSelectorEvidenceError('grapheme_boundary');
   }
 }