gcf-aif-ext 0.5.0 → 0.5.2

package/node_modules/cnlp-kit/profiles/docset.md

@@ -1,103 +1,103 @@
----
-name: docset
-description: The CNL-P profile of a docset index — the entry page of a library's agent documentation, and the closed list of what that library offers.
----
-
-format: cnlp-format.md
-
-mood: imperative
-
-headings:
-- none: an index is one flat run of blocks, and the file name carries the title
-
-frontmatter_fields:
-- none: an index is read by path, so it carries no routing contract to restate
-
-lexicon_exempt:
-- none: an index has no frontmatter, so nothing is exempt
-
-sections:
-- key: identity
-  form: keyed-block
-  required: yes
-  record_keys: library, version, source
-  optional_record_keys: derived_from
-  note: the library covered and the revision it was read at; derived_from names what the pages were written from, because a page written from prose carries less weight than one written from a signature
-
-- key: purpose
-  form: bullet-list
-  required: yes
-  note: what the library does, and the kind of task a reader reaches for it with
-
-- key: read_protocol
-  form: numbered-list
-  required: yes
-  note: how to walk this docset: the common case is written from `canonical_use:`, a page opens for any call whose contract the reader lacks, and a step telling the reader to stop reading is the defect
-
-- key: install
-  form: bullet-list
-  required: no
-  note: how a project takes the dependency; delete the block when the docset covers a dependency the project already carries
-
-- key: canonical_use
-  form: keyed-block
-  required: yes
-  record_keys: shows
-  note: 1 complete working use of the library, carrying every load-bearing element; a reader holding only the index writes the common case from this block, and an index without one is a table of contents, which is enough for nothing
-
-- key: walkthrough
-  form: record-list
-  required: yes
-  record_keys: part, page
-  note: each part of `canonical_use:` and the page owning its detail; a record and not a comment inside the fence, because a fence is opaque and a link inside one reaches no reader and no check
-
-- key: concepts
-  form: record-list
-  required: yes
-  record_keys: page, does
-  note: the models a reader holds before any page reads correctly; a record and not a line, so every link in a docset is a `page:` value and a resolver guesses at none of them
-
-- key: tasks
-  form: record-list
-  required: yes
-  record_keys: page, does
-  note: the goals a reader arrives with; a catalog keyed on capability routes a reader holding a symbol and leaves one holding a goal to guess
-
-- key: catalog
-  form: record-list
-  required: yes
-  record_keys: capability, does, status
-  optional_record_keys: page, read, instead, fingerprint
-  record_values: status = covered, source, avoid
-  note: "every capability the library offers, in 1 record each; status is covered, source or avoid, and a symbol absent here is a symbol the library lacks; fingerprint changes when the source does, so a record without one cannot report drift"
-
-- key: excluded
-  form: bullet-list
-  required: yes
-  note: a whole region the docset leaves out, with the reason; a region named in neither this block nor the catalog reads as an omission nobody decided
-
-- key: companions
-  form: record-list
-  required: yes
-  record_keys: docset, when, owns
-  note: another docset covering what this library does not; `when:` is "always" once its index carries `overrides:`, since a reader loading it on demand misses the correction; "- none" when the library stands alone
-
-- key: overrides
-  form: record-list
-  required: no
-  record_keys: page, by, reason
-  note: "a page of another docset that stops holding once this package is present, and the page here that replaces it; `page:` names the foreign page and carries its docset prefix, `by:` names the local one and carries none"
-
-- key: version_notes
-  form: bullet-list
-  required: no
-  note: what changed in the covered version, for a reader arriving from an older one
-
-custom_sections:
-- none: a project fills this from the vocabulary its own docsets already use
-
-enforcement:
-- `npx cnlp check`, over the files a `cnlp.config.json` corpus entry maps to this profile
-- any issue is an error: an index routes every other page, so a wrong index misroutes the whole docset
-- `npx cnlp check` resolves every `page:`, `by:` and `docset:` value once the project declares `docsets:`
-- `npx cnlp check` holds `status` to covered, source and avoid; what a status implies — a `read:` on source, an `instead:` on avoid — is caught by review
+---
+name: docset
+description: The CNL-P profile of a docset index — the entry page of a library's agent documentation, and the closed list of what that library offers.
+---
+
+format: cnlp-format.md
+
+mood: imperative
+
+headings:
+- none: an index is one flat run of blocks, and the file name carries the title
+
+frontmatter_fields:
+- none: an index is read by path, so it carries no routing contract to restate
+
+lexicon_exempt:
+- none: an index has no frontmatter, so nothing is exempt
+
+sections:
+- key: identity
+  form: keyed-block
+  required: yes
+  record_keys: library, version, source
+  optional_record_keys: derived_from
+  note: the library covered and the revision it was read at; `version:` opens with the version alone, as a tool reads it up to the first comma; derived_from names the sources, because prose carries less weight than a signature
+
+- key: purpose
+  form: bullet-list
+  required: yes
+  note: what the library does, and the kind of task a reader reaches for it with
+
+- key: read_protocol
+  form: numbered-list
+  required: yes
+  note: the index is the cost of every question and a page the cost of 1: the common case is written from `canonical_use:`, a page opens for a contract the reader lacks, and a step that stops the reader is the defect
+
+- key: install
+  form: bullet-list
+  required: no
+  note: how a project takes the dependency; delete the block when the docset covers a dependency the project already carries
+
+- key: canonical_use
+  form: keyed-block
+  required: yes
+  record_keys: shows
+  note: 1 complete working use of the library, carrying every load-bearing element; a reader holding only the index writes the common case from this block, and an index without one is a table of contents, which is enough for nothing
+
+- key: walkthrough
+  form: record-list
+  required: yes
+  record_keys: part, page
+  note: each part of `canonical_use:` and the page owning its detail; a record and not a comment inside the fence, because a fence is opaque and a link inside one reaches no reader and no check
+
+- key: concepts
+  form: record-list
+  required: yes
+  record_keys: page, does
+  note: the models a reader holds before any page reads correctly; a record and not a line, so every link in a docset is a `page:` value and a resolver guesses at none of them
+
+- key: tasks
+  form: record-list
+  required: yes
+  record_keys: page, does
+  note: the goals a reader arrives with; a catalog keyed on capability routes a reader holding a symbol and leaves one holding a goal to guess
+
+- key: catalog
+  form: record-list
+  required: yes
+  record_keys: capability, does, status
+  optional_record_keys: page, read, instead, fingerprint
+  record_values: status = covered, source, avoid
+  note: "every capability the library offers, in 1 record each; status is covered, source or avoid, and a symbol absent here is a symbol the library lacks; fingerprint changes when the source does, so a record without one cannot report drift"
+
+- key: excluded
+  form: bullet-list
+  required: yes
+  note: a whole region the docset leaves out, with the reason; a region named in neither this block nor the catalog reads as an omission nobody decided
+
+- key: companions
+  form: record-list
+  required: yes
+  record_keys: docset, when, owns
+  note: another docset covering what this library does not; `when:` is "always" once its index carries `overrides:`, since a reader loading it on demand misses the correction; "- none" when the library stands alone
+
+- key: overrides
+  form: record-list
+  required: no
+  record_keys: page, by, reason
+  note: "a page of another docset that stops holding once this package is present, and the page here that replaces it; `page:` names the foreign page and carries its docset prefix, `by:` names the local one and carries none"
+
+- key: version_notes
+  form: bullet-list
+  required: no
+  note: what changed in the covered version, for a reader arriving from an older one
+
+custom_sections:
+- none: a project fills this from the vocabulary its own docsets already use
+
+enforcement:
+- `npx cnlp check`, over the files a `cnlp.config.json` corpus entry maps to this profile
+- any issue is an error: an index routes every other page, so a wrong index misroutes the whole docset
+- `npx cnlp check` resolves every `page:`, `by:` and `docset:` value once the project declares `docsets:`
+- `npx cnlp check` holds `status` to covered, source and avoid; what a status implies — a `read:` on source, an `instead:` on avoid — is caught by review

package/node_modules/cnlp-kit/skills/cnlp-docset/SKILL.md

@@ -51,7 +51,7 @@ workflow:
 1. run `npx cnlp print format` and read it in full, §9 included: it states what a page reference is, and which of its rules a review holds rather than the checker
 2. read the `docset`, `concept`, `api` and `task` profiles through `npx cnlp print <name>`: their `note:` keys carry the reason behind each block, and the rules and the values are read together
 3. list every source the operator supplied and name the weight each one carries: the strongest weight in that list bounds what every page below claims, so report it before writing anything
-4. run the clone or the install command each source needs, at a fixed revision, and record the library, the version and the revision in `identity:`
+4. run the clone or the install command each source needs, at a fixed revision, and record the library in `identity:`, and in `version:` the version alone, then a comma and the revision
 5. fill `derived_from:` in `identity:` with those sources and their weights, so a reader tells a set written from declarations from a set written from prose
 6. list every capability of the library, taking each one from the strongest source that states it: a source at weight 3 or below covers what its author chose to cover, so a capability it omits is a capability still to find
 7. fill `catalog:` with 1 record per capability, every one at `status: source`, `read:` naming where to read it — the file, or the document and the anchor inside it
@@ -63,9 +63,11 @@ workflow:
 13. write 1 task page per goal a reader arrives with, and put the multi-call composition there
 14. update each catalog record to `covered` as its page lands, and fill `excluded:` with every whole region the set leaves out, each with its reason
 15. fill `companions:` when another package extends this library, and `overrides:` when this package corrects a page of the set it extends
-16. run `npx cnlp check <output_directory>` and fix what it reports: it resolves every reference in the set, and reports a page no other page reaches
-17. read the finished set for the rules no check reaches: 1 fact stated on 1 page, 1 running example across the set, 1 page per routed name, and the keys a status implies
-18. report the capabilities covered, the ones left at `source`, the weight the set rests on, and any defect the reading turned up in the library itself
+16. name every set `companions:` or `overrides:` names that does not sit beside `<output_directory>`, and the directory holding it: the check resolves a crossing only against a set it can read
+17. run `npx cnlp check <output_directory>`, with `--companion <set>=<dir>` for each set step 16 named, and fix what it reports: it resolves every reference in the set, and reports a page no other page reaches
+18. read the finished set for the rules no check reaches: 1 fact stated on 1 page, 1 running example across the set, 1 page per routed name, and the keys a status implies
+19. read each task page against the API pages it sends a reader to: a member the task steers away from carries that in its own `pitfalls:`, because a full API page otherwise outvotes a task page's preference
+20. report the capabilities covered, the ones left at `source`, the weight the set rests on, and any defect the reading turned up in the library itself
 
 invocation:
 - Claude Code: `/cnlp-docset <sources> <output-directory>`, once this folder sits in `.claude/skills/`

package/node_modules/cnlp-kit/src/cnlp.js

@@ -29,21 +29,57 @@ export const HARD_LIMIT = 250; // §4: 150 is the target, 250 is compound whatev
 
 const FORMS = new Set(['scalar', 'bullet-list', 'numbered-list', 'record-list', 'keyed-block']);
 const KEY = /^([a-z][a-z0-9_]*):(.*)$/;
+/** §3: a line that is 1 whole comment. `<!-- a --> - item` carries an item, and is read. */
+const COMMENT = /^\s*<!--(?:(?!-->).)*-->\s*$/;
+/** §3: the markers of a region another tool writes into the file. */
+const REGION = /^\s*<!--\s*([\w.-]+):(start|end)\s*-->\s*$/;
 
 /**
- * Body split into lines, top-level `key:` sections and `##` headings, with fenced regions
- * blanked — §3: a fence is opaque, its contents are data and never section keys.
- * Leading frontmatter is stripped when present. Line numbers are 1-based within the body.
+ * Body split into lines, top-level `key:` sections and `##` headings. §3: a fence is blanked in
+ * both `lines` and `prose`, because its contents are data. An HTML comment and a marked region are
+ * blanked in `lines` only, which is the shape the profile reads: both stay in `prose`, which the
+ * lexicon reads, because an agent reads the raw file. Leading frontmatter is blanked when
+ * present. Line numbers are 1-based within the file.
  */
 export function parseBlocks(raw) {
-  const body = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+  // Blanked, not removed: a reported line is a line of the file, frontmatter included.
+  const body = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, (m) => '\n'.repeat(m.split('\n').length - 1));
+  const source = body.split(/\r?\n/);
+  // A comment that never closes hides nothing: it would otherwise exempt the rest of the file.
+  const lastClose = source.findLastIndex((l) => l.includes('-->'));
   let fenced = false;
+  let comment = false;
   const fences = []; // 1-based line numbers a fence covered: blanked, but not absent
-  const lines = body.split(/\r?\n/).map((l, i) => {
+  const marks = [];
+  const hidden = new Map(); // 0-based line -> what is left of it once its comment is taken off
+  const prose = source.map((l, i) => {
+    if (comment) {
+      const end = l.indexOf('-->');
+      if (end >= 0) comment = false;
+      hidden.set(i, end < 0 ? '' : l.slice(end + 3));
+      return l;
+    }
     if (/^\s*```/.test(l)) { fenced = !fenced; fences.push(i + 1); return ''; }
     if (fenced) { fences.push(i + 1); return ''; }
+    const mark = l.match(REGION);
+    if (mark) marks.push({ name: mark[1], end: mark[2] === 'end', at: i });
+    if (COMMENT.test(l)) hidden.set(i, '');
+    else if (/^\s*<!--/.test(l) && !l.includes('-->') && i < lastClose) { comment = true; hidden.set(i, ''); }
     return l;
   });
+  // An end closes the latest start of its own name, so regions of 2 names never cancel each other.
+  // A start with no end marks nothing, and an end with no start is a comment like any other.
+  const regions = [];
+  const open = new Map();
+  for (const m of marks) {
+    if (!m.end) open.set(m.name, m.at);
+    else if (open.has(m.name)) {
+      regions.push({ name: m.name, line: open.get(m.name) + 1, end: m.at + 1 });
+      open.delete(m.name);
+    }
+  }
+  const inRegion = (i) => regions.some((r) => i + 1 > r.line && i + 1 < r.end);
+  const lines = prose.map((l, i) => (inRegion(i) ? '' : hidden.get(i) ?? l));
   const sections = [];
   const headings = [];
   lines.forEach((l, i) => {
@@ -51,7 +87,8 @@ export function parseBlocks(raw) {
     if (key) sections.push({ key: key[1], value: key[2].trim(), line: i + 1 });
     if (/^##\s/.test(l)) headings.push({ text: l.trim(), line: i + 1 });
   });
-  return { lines, sections, headings, fences: new Set(fences) };
+  // A fence inside a region is the region's content, not content of the block above the region.
+  return { lines, prose, sections, headings, fences: new Set(fences.filter((n) => !inRegion(n - 1))), regions };
 }
 
 /** Lines of a section: everything up to the next top-level key or `##` heading. */
@@ -202,7 +239,7 @@ export async function loadProfile(name, opts) {
  * about the document as a whole.
  */
 export function bodyIssues(raw, profile) {
-  const { lines, sections, headings, fences } = parseBlocks(raw);
+  const { lines, prose, sections, headings, fences } = parseBlocks(raw);
   const issues = [];
   const at = (line, message) => issues.push({ line, message });
   const byKey = new Map(profile.sections.map((s) => [s.key, s]));
@@ -271,7 +308,8 @@ export function bodyIssues(raw, profile) {
     issues.push(...formIssues(key, spec, items));
   }
 
-  issues.push(...lexiconIssues(lines, profile.mood));
+  // A region is exempt from the file's shape, not from the language: the lexicon reads it.
+  issues.push(...lexiconIssues(prose, profile.mood));
   return issues.sort((a, b) => a.line - b.line);
 }
 
@@ -502,7 +540,9 @@ export function lexiconIssues(lines, mood = '') {
     // A converted document is where these 2 turn up: a mechanical split reads an ordinal as a
     // sentence and leaves `- 4` behind, and cutting a line to the hard limit lands mid-span.
     const item = l.match(/^\s*(?:[-*]|\d+\.)\s+(.*)$/);
-    if (item && !/[a-z]/i.test(item[1])) issues.push({ line, message: 'the item carries no word — it states no claim' });
+    // Any script's letter, not an ASCII one: the rule rejects an item made of digits and
+    // punctuation, and a body written in Cyrillic or CJK states its claims in letters too.
+    if (item && !/\p{L}/u.test(item[1])) issues.push({ line, message: 'the item carries no word — it states no claim' });
     for (const [name, open, close] of UNCLOSED) {
       const n = (l.match(open) || []).length;
       if (close ? n !== (l.match(close) || []).length : n % 2) {
@@ -531,4 +571,26 @@ export function lexiconIssues(lines, mood = '') {
   return issues;
 }
 
+/**
+ * Whether the §5 lexicon reaches a document. Every word list in §5 — the deny list, the spelled
+ * thresholds, the open limits, the comparatives, the light verbs, the passive — is English, so a
+ * body written in another script matches none of them and would report clean against rules that
+ * never ran. The prose decides it, which is the line with its section key, its heading marker and
+ * its quoted spans taken off: a key is this format's own vocabulary and English in every document,
+ * and a Russian line naming `CombatFeature.cs` is still a Russian line.
+ * ponytail: this reads script, not language — a German or a Spanish body reads as English here, and
+ * only its reader can say otherwise.
+ */
+export function lexiconApplies(raw) {
+  const prose = raw
+    .replace(/```[\s\S]*?```/g, ' ')
+    .split(/\r?\n/)
+    .filter((l) => !/^\s*#/.test(l))
+    .map((l) => unquoted(l).replace(/^\s*(?:[-*]\s+|\d+\.\s+)?[a-z][a-z0-9_]*:/, ' '))
+    .join('\n');
+  const letters = prose.match(/\p{L}/gu) ?? [];
+  const latin = letters.filter((c) => /[a-z]/i.test(c)).length;
+  return latin * 2 >= letters.length;
+}
+
 export { FORMS };