gcf-aif-ext 0.5.1 → 0.5.3

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

@@ -4,9 +4,9 @@
 // inside a file the next upgrade overwrote.
 
 import { existsSync } from 'node:fs';
-import { glob, readdir, readFile } from 'node:fs/promises';
+import { glob, readdir, readFile, realpath } from 'node:fs/promises';
 import path from 'node:path';
-import { bodyIssues, loadProfileAt, pageRefs, resolveDoc } from './cnlp.js';
+import { bodyIssues, lexiconApplies, loadProfileAt, pageRefs, parseBlocks, resolveDoc } from './cnlp.js';
 
 export const CONFIG_NAME = 'cnlp.config.json';
 
@@ -124,24 +124,48 @@ export function readingOrder(sets) {
   return out;
 }
 
+/** `pageIdOf`, with the set renamed when the caller named it apart from its directory. */
+const renamedIdOf = (rel, docsets, rename) => {
+  const id = pageIdOf(rel, docsets);
+  return id && { ...id, docset: rename[id.docset] ?? id.docset };
+};
+
 /**
  * §9 reference conformance across a corpus, which is the 1 check no single document can make.
  * `docs` is every file already read, so this adds no read of its own.
+ *
+ * `context` holds the pages of companion sets as `{ set, page, raw }`: they resolve references and
+ * are never checked. Their id comes with them rather than from a path, because a companion may sit
+ * outside the root, in a folder named by a version rather than by its set.
  */
-export function linkIssues(docs, docsets) {
+export function linkIssues(docs, docsets, { context = [], rename = {} } = {}) {
   const pages = new Map();
   const sets = new Set();
   for (const { rel } of docs) {
-    const id = pageIdOf(rel, docsets);
+    const id = renamedIdOf(rel, docsets, rename);
     if (!id) continue;
     pages.set(`${id.docset}:${id.page}`, rel);
     sets.add(id.docset);
   }
+  const known = new Set(pages.keys());
+  for (const { set, page } of context) {
+    known.add(`${set}:${page}`);
+    sets.add(set);
+  }
 
   const issues = [];
   const reached = new Set();
+  // A companion's references are not this run's to report, but they count toward reach: a page of
+  // an integration set is reached only from the companion that overrides it.
+  for (const { set, page, raw } of context) {
+    for (const ref of pageRefs(raw)) {
+      if (ref.key === 'docset') continue;
+      const qualified = ref.target.includes(':') ? ref.target : `${set}:${ref.target}`;
+      if (qualified !== `${set}:${page}`) reached.add(qualified);
+    }
+  }
   for (const { rel, raw } of docs) {
-    const from = pageIdOf(rel, docsets);
+    const from = renamedIdOf(rel, docsets, rename);
     if (!from) continue;
     const self = `${from.docset}:${from.page}`;
     for (const ref of pageRefs(raw)) {
@@ -157,7 +181,7 @@ export function linkIssues(docs, docsets) {
       if (ref.key === 'by' && ref.target.includes(':')) {
         issues.push({ file: rel, line: ref.line, message: `"by: ${ref.target}" carries a document set prefix — a "by:" value names a page of this set` });
       }
-      if (!pages.has(qualified)) {
+      if (!known.has(qualified)) {
         issues.push({ file: rel, line: ref.line, message: `page "${qualified}" does not resolve to a file under ${docsets}/` });
       } else if (qualified !== self) {
         reached.add(qualified);
@@ -217,6 +241,85 @@ export async function skillDrift(root, agents, version) {
   return out;
 }
 
+/**
+ * The standing rules `cnlp init` hands an operator to paste into the file their agent reads. 1
+ * value and not a string inside the command, because `cnlp check` reads it too: a pasted copy is a
+ * copy that goes stale, and nothing else in the project records that it was taken.
+ */
+export const AGENT_BLOCK = [
+  '- the CNL-P standard is the authority on document form: read it with `npx cnlp print format`',
+  '- run `npx cnlp check` before a commit that touches a document the corpus names',
+  "- load a library's documentation with `npx cnlp docs`, which writes every set's index in reading order",
+];
+
+// The 2 files an agent reads by convention, which are the 2 the corpus proposal below already
+// knows. The block is pasted by hand, so nothing records which file took it.
+const AGENT_FILES = ['AGENTS.md', 'CLAUDE.md'];
+
+/**
+ * The agent files carrying a copy of `AGENT_BLOCK` from an earlier version. A bullet naming
+ * `npx cnlp print format` is the block's own opener and is what finds the copy.
+ * ponytail: that phrase is the anchor — a version that stops naming it loses the watch on every
+ * copy already pasted, and the answer then is markers written into the file.
+ */
+export async function agentBlockDrift(root) {
+  const out = [];
+  for (const name of AGENT_FILES) {
+    const at = path.join(root, name);
+    if (!existsSync(at)) continue;
+    const lines = (await readFile(at, 'utf8')).split(/\r?\n/).map((l) => l.trimEnd());
+    const start = lines.findIndex((l) => /^-\s.*`npx cnlp print format`/.test(l));
+    if (start < 0) continue; // the project never took the block
+    if (lines.slice(start, start + AGENT_BLOCK.length).join('\n') !== AGENT_BLOCK.join('\n')) out.push(name);
+  }
+  return out;
+}
+
+/**
+ * The local profiles a packaged profile of the same name has outgrown. A project copies a packaged
+ * profile to fill its own `custom_sections`, and `profileFor` reads the copy from then on: an
+ * upgrade moves the original underneath it, and the check reports a conformant corpus against a
+ * declaration this package has since changed. What a copy adds is the vocabulary it was copied for
+ * and is never drift; what the packaged profile declares and the copy does not is.
+ */
+export async function profileDrift(config) {
+  const out = [];
+  if (!config.profilesDir) return out;
+  for (const name of [...new Set(config.corpus.map((e) => e.profile))].sort()) {
+    const local = path.join(config.profilesDir, `${name}.md`);
+    const packagedAt = resolveDoc(name);
+    if (!existsSync(local) || !existsSync(packagedAt) || path.resolve(packagedAt) === path.resolve(local)) continue;
+    const packaged = await loadProfileAt(packagedAt);
+    const mine = await loadProfileAt(local);
+    const byKey = new Map(mine.sections.map((s) => [s.key, s]));
+    const missing = [];
+    for (const want of packaged.sections) {
+      const has = byKey.get(want.key);
+      if (!has) {
+        missing.push(`section "${want.key}"`);
+        continue;
+      }
+      if (has.form !== want.form) missing.push(`section "${want.key}" as a ${want.form}`);
+      if (want.required && !has.required) missing.push(`section "${want.key}" as required`);
+      for (const k of want.recordKeys) {
+        if (!has.recordKeys.includes(k)) missing.push(`record key "${want.key}.${k}"`);
+      }
+    }
+    for (const h of packaged.headings) {
+      if (!mine.headings.includes(h)) missing.push(`heading "${h}"`);
+    }
+    for (const f of packaged.frontmatterFields) {
+      if (!mine.frontmatterFields.includes(f)) missing.push(`frontmatter field "${f}"`);
+    }
+    if (packaged.mood && packaged.mood !== mine.mood) missing.push(`mood "${packaged.mood}"`);
+    // Forward slashes, like every other path this reports: the checker names a file the same way
+    // on every platform.
+    const rel = path.relative(config.root, local).split(path.sep).join('/');
+    if (missing.length) out.push({ profile: name, file: rel, missing });
+  }
+  return out;
+}
+
 // The layouts a corpus entry is usually written for. `cnlp init` keeps the ones that match a file,
 // so a project adopting the format starts from its own layout rather than from an example of one.
 // ponytail: path convention only, never content — a decision record filed under docs/references
@@ -272,21 +375,69 @@ export async function proposeCorpus(root) {
  * An entry matching no file is dropped here, which a written config is right to refuse: a glob a
  * project typed and no file answers is a mistake, and a glob this function guessed is a folder the
  * set does not have yet.
+ *
+ * 1 set checked alone still resolves its crossings: `companions` names the sets it crosses into,
+ * each `{ name, dir }`, and the sets beside it join as companions named by their directories. A
+ * companion is read to resolve a reference and never checked. `name` names the checked set when
+ * its directory does not, as in a layout of `<set>/<version>/`.
  */
-export async function configForPath(dir) {
-  const abs = path.resolve(dir);
-  if (!existsSync(abs)) throw new Error(`no such directory: ${dir}`);
+export async function configForPath(dir, { name, companions: named = [] } = {}) {
+  if (!existsSync(path.resolve(dir))) throw new Error(`no such directory: ${dir}`);
+  // The spelling on disk, not the one typed: on a case-insensitive disk `DragonECS-Unity` would
+  // otherwise miss its own directory among the siblings and read itself as a companion.
+  const abs = await realpath(path.resolve(dir));
+  if (!Array.isArray(named)) throw new Error(`companions is a list of { name, dir }, found ${JSON.stringify(named)}`);
   let root;
   let docsets = null;
   let corpus;
-  if (existsSync(path.join(abs, 'index.md'))) {
+  const oneSet = existsSync(path.join(abs, 'index.md'));
+  // A root check already reads every set under it, and a project has no single set to name.
+  if (!oneSet && (name !== undefined || named.length)) {
+    throw new Error(`${abs} is not 1 document set — a name and companions apply to a directory holding an index.md`);
+  }
+  const base = path.basename(abs);
+  const setName = name ?? base;
+  const companions = [];
+  if (oneSet) {
+    if (name !== undefined) checkSetName(name, 'the checked set');
+    for (const c of named) {
+      checkSetName(c.name, 'a companion');
+      if (!c.dir) throw new Error(`companion "${c.name}" names no dir — give the directory of 1 document set`);
+      if (!existsSync(path.resolve(c.dir))) throw new Error(`companion "${c.name}": no such directory: ${path.resolve(c.dir)}`);
+      const at = await realpath(path.resolve(c.dir));
+      // The checked set read again under another name would reach its own pages through the copy.
+      if (at === abs) throw new Error(`companion "${c.name}" is the checked set itself — name another set`);
+      if (!existsSync(path.join(at, 'index.md'))) {
+        throw new Error(`companion "${c.name}": ${at} holds no index.md — name the directory of 1 document set`);
+      }
+      if (c.name === setName) throw new Error(`companion "${c.name}" carries the name of the checked set — name it apart`);
+      if (companions.some((o) => o.name === c.name)) throw new Error(`companion "${c.name}" is named twice — name each set once`);
+      companions.push({ name: c.name, dir: at });
+    }
+    // A set is present because a project vendors it, so the sets beside it are its companions.
+    // A name apart from the directory means no flat layout: the siblings there are other versions
+    // of the same set, and reading them as sets would resolve nothing.
+    // ponytail: a sibling's name is its directory's and is not held to `checkSetName`; a directory
+    // carrying ":" is possible only off Windows, and it would print as a set nobody can reference.
+    if (setName === base) {
+      const parent = path.dirname(abs);
+      for (const entry of (await readdir(parent, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+        const at = path.join(parent, entry.name);
+        if (!entry.isDirectory() || entry.name === base || !existsSync(path.join(at, 'index.md'))) continue;
+        // An explicit companion wins, by name or by directory: 1 set is read once.
+        if (companions.some((o) => o.name === entry.name || o.dir === at)) continue;
+        companions.push({ name: entry.name, dir: at });
+      }
+    }
+  }
+  if (oneSet) {
     root = path.dirname(path.dirname(abs));
     docsets = path.basename(path.dirname(abs));
-    corpus = docsetCorpus(`${docsets}/${path.basename(abs)}`);
+    corpus = docsetCorpus(`${globLiteral(docsets)}/${globLiteral(base)}`);
   } else if (await holdsASet(abs)) {
     root = path.dirname(abs);
     docsets = path.basename(abs);
-    corpus = docsetCorpus(`${docsets}/*`);
+    corpus = docsetCorpus(`${globLiteral(docsets)}/*`);
   } else {
     // Neither shape: fall back to the layouts `cnlp init` already knows, so pointing at a project
     // reads the same as pointing at a set.
@@ -301,7 +452,29 @@ export async function configForPath(dir) {
   if (kept.length === 0) {
     throw new Error(`${abs} holds no document this kit knows the layout of — a document set is an index.md beside concepts, api and tasks`);
   }
-  return { path: null, root, profilesDir: null, docsets, corpus: kept, agents: [] };
+  // `companions` is always present, `[]` included: a caller tells a kit that ignores the option
+  // from a set that failed by this field's absence.
+  const rename = setName === base ? {} : { [base]: setName };
+  return { path: null, root, profilesDir: null, docsets, corpus: kept, agents: [], companions, rename };
+}
+
+/** A set name keys every page id, and `:` separates `<set>:<name>`, so a name carrying it reads as a page. */
+function checkSetName(name, whose) {
+  if (typeof name !== 'string' || name === '' || /[:/\\]/.test(name)) {
+    throw new Error(`${JSON.stringify(name)} is no name for ${whose} — a set name is not empty and carries no ":", "/" or "\\"`);
+  }
+}
+
+/**
+ * A directory name as a glob that matches only itself. The corpus is a glob, and a set in
+ * `2.0.0-[rc]` otherwise reads as a character class that matches no directory, which reports
+ * the set as holding no document. A class of 1 character is the escape `fs.glob` honours: it
+ * reads `\` as a separator on Windows.
+ * ponytail: a `{` still opens a brace set, which no escape reaches through `fs.glob`; a set
+ * directory named with braces needs a config instead of a path.
+ */
+function globLiteral(name) {
+  return name.replace(/[[*?]/g, (c) => `[${c}]`);
 }
 
 /** Whether an immediate subdirectory carries an index.md, which is what makes a directory a root. */
@@ -329,10 +502,40 @@ export async function filesFor(entry, root) {
  * Run every corpus entry. Returns the files checked and the issues found, each carrying the
  * project-relative path it came from. Severity is the caller's: an issue is an issue here.
  */
+/**
+ * The bytes a document set costs a reader, split by when they are paid. The index is loaded to
+ * answer any question and a page is loaded to answer 1, so the 2 numbers are different kinds of
+ * cost, and an author trimming the wrong one saves a reader nothing.
+ *
+ * Computed from the documents the caller has already read, so this adds no read of its own.
+ */
+export function setSizes(docs, docsets, rename = {}) {
+  const sets = new Map();
+  for (const { rel, raw } of docs) {
+    const id = renamedIdOf(rel, docsets, rename);
+    if (!id) continue;
+    const set = sets.get(id.docset) ?? { name: id.docset, indexBytes: 0, pages: 0, pageBytes: 0 };
+    const bytes = Buffer.byteLength(raw, 'utf8');
+    if (id.page === 'index') set.indexBytes += bytes;
+    else {
+      set.pages += 1;
+      set.pageBytes += bytes;
+    }
+    sets.set(id.docset, set);
+  }
+  return [...sets.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
 export async function checkProject(config) {
   const issues = [];
   const checked = [];
   const docs = [];
+  // A document the §5 word lists never reach. It is not an issue — nothing in it is wrong — but a
+  // run that says nothing about it reports a conformant corpus over rules that never ran.
+  const foreign = [];
+  // §3: a marked region the file's profile did not shape. Reported for the same reason: a run that
+  // names no exemption reads as a check of every line, and a region is an exemption anybody can write.
+  const regions = [];
   for (const entry of config.corpus) {
     const files = await filesFor(entry, config.root);
     if (files.length === 0) {
@@ -343,10 +546,25 @@ export async function checkProject(config) {
       const raw = await readFile(path.join(config.root, rel), 'utf8');
       checked.push(rel);
       docs.push({ rel, raw });
+      if (!lexiconApplies(raw)) foreign.push(rel);
+      for (const r of parseBlocks(raw).regions) regions.push({ file: rel, ...r });
       for (const issue of bodyIssues(raw, profile)) issues.push({ file: rel, ...issue });
     }
   }
+  // A config from `readConfig` carries neither field: it already reads every set under its root.
+  const rename = config.rename ?? {};
+  // A companion's pages resolve references and are counted nowhere: the run reports on the set it
+  // was pointed at. `docsetCorpus` is the 1 place the shape of a set is written, so it is read here too.
+  const context = [];
+  for (const { name, dir } of config.companions ?? []) {
+    for (const entry of docsetCorpus('.')) {
+      for (const rel of await filesFor(entry, dir)) {
+        const page = rel.split(path.sep).join('/').slice(0, -3);
+        context.push({ set: name, page, raw: await readFile(path.join(dir, rel), 'utf8') });
+      }
+    }
+  }
   // §9 is the 1 rule that needs the whole corpus, so it runs once over the files already read.
-  if (config.docsets) issues.push(...linkIssues(docs, config.docsets));
-  return { checked, issues };
+  if (config.docsets) issues.push(...linkIssues(docs, config.docsets, { context, rename }));
+  return { checked, issues, foreign, regions, sets: config.docsets ? setSizes(docs, config.docsets, rename) : [] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",
@@ -42,7 +42,7 @@
     "README.md"
   ],
   "dependencies": {
-    "cnlp-kit": "^3.1.3",
+    "cnlp-kit": "^3.9.1",
     "yaml": "^2.5.1"
   },
   "bundleDependencies": [

package/skills/gcf-audit/SKILL.md

@@ -19,10 +19,11 @@ workflow:
 1. run `ai-factory gcf audit --json` and read the report
 2. state the first line verbatim: items waiting too long block dependent work, so they lead
 3. for each stale until record: name the file, the trigger that fired and the line to re-check; for each entry of `stale_questions`: name the question id and ask the human for the answer
-4. read the `design` summary: blocking findings first (run `ai-factory gcf design check` for the list), then the count of ready units
-5. semantic pass, only when the mechanical report is clean or the human asks: read the systems docs of ONE subsystem the human names and report pairs of lines that contradict each other as D1 questions
-6. list the pragmas: each `gcf:allow` is a standing exception, and a growing list is the linter rotting
-7. propose the next actions, ranked, proposed actions <= 3: playtest, answer a D1, take a ready unit, or collapse a stale record
+4. for a stale until record of `gcf/open-questions.md`: the D2 assumption its `id` names expired - ask the human to confirm it, then cite `answer: <id>` and remove the record, or to replace the value
+5. read the `design` summary: blocking findings first (run `ai-factory gcf design check` for the list), then the count of ready units
+6. semantic pass, only when the mechanical report is clean or the human asks: read the systems docs of ONE subsystem the human names and report pairs of lines that contradict each other as D1 questions
+7. list the pragmas: each `gcf:allow` is a standing exception, and a growing list is the linter rotting
+8. propose the next actions, ranked, proposed actions <= 3: playtest, answer a D1, take a ready unit, or collapse a stale record
 
 invocation:
 - run at session start, after a long break, or on demand

package/skills/gcf-init/SKILL.md

@@ -15,7 +15,7 @@ preconditions:
 - the project is a git repository with AI Factory initialized
 
 forbidden_behaviors:
-- do not overwrite an existing gcf/ tree: re-running repairs missing files only
+- do not overwrite an existing gcf/ tree: re-running repairs missing files, refreshes the AGENTS.md block and restamps a 0.4.0 `frozen:`
 - do not write pillars the human did not confirm: pillar authorship is human
 - pillar count <= 7, and do not pad the list to reach 7