@ansonlai/docx-redline-js 0.6.1 → 0.6.2

package/docs/AGENT_FAST_START.md

@@ -23,7 +23,7 @@ It is a development sample, not a package API.
    docx-redline extract contract.docx --search "termination" --around 3
    ```
 
-   Search is case-insensitive. Direct hits are capped; follow `selection.nextAfter` with `--after`, and cite `humanReference`, not `P42`.
+   Search is case-insensitive; follow `selection.hint` if 0 matches were found for restorable text. Direct hits are capped; follow `selection.nextAfter` with `--after`, and cite `humanReference`, not `P42`.
 
 2. Copy `exactText` with `paragraphId` or `fingerprint`. Use a UTF-8 operations
    file or serializer-backed stdin, then apply once:

package/docs/AGENT_KNOWLEDGE_BASE.md

@@ -575,12 +575,17 @@ normalize or reconstruct `exactText`. Operation files follow
 Paragraph indexes are 1-based. Inspection filters are `--index 12`,
 `--range 10:30`, `--indexes 2,5,8`, `--search text`, `--revised`, `--table`,
 `--body`, `--non-empty`, and `--view accepted|rejected|current`. Search is
-case-insensitive. Add `--around N` (`--context N` or `-C N`) to a search;
+case-insensitive. When a search returns 0 matches in the active view but matches
+exist in the alternate view (such as searching for a deleted clause to restore),
+`selection.hint` provides immediate guidance to re-run with `--view rejected`.
+Add `--around N` (`--context N` or `-C N`) to a search;
 context records are labeled separately and do not consume the direct-hit
 `--limit`. Continue a bounded result with `--after <paragraph-index>`. Ordinary
 unscoped CLI inspection defaults to 20 direct records and a 48 KiB soft budget;
 `--all` deliberately opts out. A malformed filter or unknown option is an error
-rather than an unfiltered fallback.
+rather than an unfiltered fallback. CLI help commands (`apply --help`,
+`extract --help`, `--help`) report canonical GitHub repository URLs in their
+`documentation` array.
 
 Mutating commands use `--author`, operation-level authors, then
 `DOCX_REDLINE_AUTHOR`, falling back visibly to `AI Redliner`; review-resolution

package/docs/SKILL_AUTHORING.md

@@ -87,9 +87,12 @@ focused contextual extraction:
 docx-redline extract input.docx --search "force majeure" --around 3
 ```
 
-Use `selection.nextAfter` with `--after` when truncated. Apply once per stable
-batch. Run `docx-redline apply --help` for canonical redline, whole-paragraph
-comment, and rejected-view restore shapes; the operation schema remains
+Use `selection.nextAfter` with `--after` when truncated. When a search for
+deleted or restorable content yields 0 matches in accepted view, follow
+`selection.hint` and re-run with `--view rejected`. Apply once per stable batch.
+Run `docx-redline apply --help` for canonical redline, whole-paragraph comment,
+and rejected-view restore shapes; CLI help documentation fields return canonical
+GitHub URLs. The operation schema remains
 [document-operations.schema.json](schemas/document-operations.schema.json).
 
 ## Recovery contract

package/node/cli-help.js

@@ -182,6 +182,14 @@ export function commandOptionKeys(command) {
     return (CLI_COMMAND_HELP[command]?.options || []).map(item => item.key);
 }
 
+const DOCS_BASE_URL = 'https://github.com/AnsonLai/docx-redline-js/blob/main/';
+export const CLI_DOCUMENTATION_URLS = Object.freeze([
+    `${DOCS_BASE_URL}AGENTS.md`,
+    `${DOCS_BASE_URL}docs/AGENT_FAST_START.md`,
+    `${DOCS_BASE_URL}docs/SKILL_AUTHORING.md`,
+    `${DOCS_BASE_URL}docs/schemas/document-operations.schema.json`
+]);
+
 export function buildCliHelp(command = null) {
     if (!command) {
         return {
@@ -190,7 +198,7 @@ export function buildCliHelp(command = null) {
             usage: 'docx-redline <command> [file.docx] [options]',
             commands: CLI_COMMANDS.map(name => ({ name, summary: CLI_COMMAND_HELP[name].summary })),
             notes: ['Run docx-redline <command> --help for flags, semantics, and bounded examples.'],
-            documentation: ['AGENTS.md', 'docs/AGENT_FAST_START.md', 'docs/SKILL_AUTHORING.md', 'docs/schemas/document-operations.schema.json']
+            documentation: [...CLI_DOCUMENTATION_URLS]
         };
     }
     const entry = CLI_COMMAND_HELP[command];
@@ -204,6 +212,7 @@ export function buildCliHelp(command = null) {
         options: entry.options.map(({ key: _key, ...publicOption }) => publicOption),
         notes: entry.notes,
         examples: entry.examples,
-        documentation: ['AGENTS.md', 'docs/AGENT_FAST_START.md', 'docs/SKILL_AUTHORING.md', 'docs/schemas/document-operations.schema.json']
+        documentation: [...CLI_DOCUMENTATION_URLS]
     };
 }
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansonlai/docx-redline-js",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
   "license": "MIT",
   "type": "module",

package/services/document-inspection.js

@@ -309,6 +309,36 @@ export function inspectDocumentParts(parts, options = {}) {
         comments.set(id, definition);
     }
     const selected = selectInspectionParagraphs(paragraphs, options);
+    if (options.search && selected.selection && selected.selection.totalMatches === 0) {
+        const needle = String(options.search).toLowerCase();
+        const alternateView = revisionView === 'accepted' ? 'rejected' : 'accepted';
+        let rangeStart = 1;
+        let rangeEnd = paragraphNodes.length;
+        if (options.range) {
+            rangeStart = Number(options.range.start ?? options.range[0]);
+            rangeEnd = Number(options.range.end ?? options.range[1]);
+        }
+        let alternateMatches = 0;
+        for (let i = 0; i < paragraphNodes.length; i++) {
+            const index = i + 1;
+            if (options.range && (index < rangeStart || index > rangeEnd)) continue;
+            if (Array.isArray(options.indexes) && !options.indexes.includes(index)) continue;
+            const pNode = paragraphNodes[i];
+            if (options.table && !hasAncestor(pNode, 'tc')) continue;
+            if (options.body && hasAncestor(pNode, 'tc')) continue;
+            if (options.revised && revisionAuthors(pNode).length === 0) continue;
+            const altText = extractCanonicalParagraphText(pNode, { revisionView: alternateView });
+            if (options.skipEmpty && altText.length === 0) continue;
+            if (altText.toLowerCase().includes(needle)) {
+                alternateMatches++;
+            }
+        }
+        if (alternateMatches > 0) {
+            selected.selection.hint = revisionView === 'accepted'
+                ? `0 matches in accepted view, but ${alternateMatches} match${alternateMatches === 1 ? '' : 'es'} found in --view rejected. If searching for deleted text to restore, re-run with --view rejected.`
+                : `0 matches in rejected view, but ${alternateMatches} match${alternateMatches === 1 ? '' : 'es'} found in --view accepted. Re-run with --view accepted.`;
+        }
+    }
     paragraphs = selected.paragraphs;
     const allRevisionAuthors = [...new Set(paragraphs.flatMap(item => item.revisionAuthors))].sort();
     const coveredEntries = extractDocumentPartsEntries(parts);