@assuredloop/cli 0.2.4 → 2.0.0

package/src/v4/phrases.js

@@ -0,0 +1,78 @@
+// Phrases for the review (issue-hints R2, design.md 3): the phrases and
+// patterns that `phrases:` in .assuredloop/config.yaml lists. al check gives
+// the hint `phrase` for each match in the spec docs, the ADRs and the
+// Markdown files of each open request, but origin/; with --issues, in the
+// issues too (issues.js). The list is empty by default.
+import { read } from './base.js';
+import { requestMarkdown } from './blocks.js';
+import { SPEC } from './scope.js';
+import { Fail } from './spec.js';
+
+const NEXT = 'fix phrases: in .assuredloop/config.yaml';
+
+// The matchers of the config: [{ entry, re }]. A bad list, entry or pattern
+// is a refusal that names it (D6).
+export function loadPhrases(config) {
+  const list = config.phrases;
+  if (list == null) return [];
+  if (!Array.isArray(list)) throw new Fail('.assuredloop/config.yaml: phrases: is not a list', NEXT);
+  return list.map((e, i) => {
+    const at = `phrases: entry ${i + 1}`;
+    if (typeof e === 'string') {
+      if (!e.trim()) throw new Fail(`.assuredloop/config.yaml: ${at} is an empty phrase`, NEXT);
+      // Ignoring case; a space matches any run of white space, a line break too.
+      const source = e.trim().split(/\s+/).map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('\\s+');
+      return { entry: e, re: new RegExp(source, 'gi') };
+    }
+    const pattern = e && typeof e === 'object' && !Array.isArray(e) ? e.pattern : undefined;
+    if (typeof pattern !== 'string') throw new Fail(`.assuredloop/config.yaml: ${at} is neither a phrase nor a mapping with a pattern`, NEXT);
+    if (!pattern) throw new Fail(`.assuredloop/config.yaml: ${at} is an empty pattern`, NEXT);
+    try {
+      return { entry: pattern, re: new RegExp(pattern, 'g') };
+    } catch (err) {
+      throw new Fail(`.assuredloop/config.yaml: ${at}, the pattern ${JSON.stringify(pattern)}, is not a valid regular expression: ${err.message}`, NEXT);
+    }
+  });
+}
+
+// Each match in `text`: [{ line, entry, match }], the line where it starts.
+// A match of no characters is not counted.
+export function phraseHits(text, matchers) {
+  const t = text.replace(/\r\n?/g, '\n');
+  const hits = [];
+  for (const { entry, re } of matchers) {
+    re.lastIndex = 0;
+    for (const m of t.matchAll(re)) {
+      if (!m[0]) continue;
+      hits.push({ line: t.slice(0, m.index).split('\n').length, entry, match: m[0] });
+    }
+  }
+  return hits.sort((a, b) => a.line - b.line);
+}
+
+export const phraseMessage = (h) => `matches ${JSON.stringify(h.entry)}: ${JSON.stringify(h.match.replace(/\s+/g, ' '))}`;
+
+// The hints in the spec docs, the ADRs and the open requests' Markdown files.
+export function phraseFindings(top, state, matchers, add) {
+  if (!matchers.length) return;
+  const files = [
+    ...(state.docs ?? []).filter((d) => d.scope === SPEC && typeof d.text === 'string').map((d) => [d.path, d.text]),
+    ...[...state.adrs.values()].map((a) => [a.file, a.text]),
+  ];
+  for (const r of state.requests.values()) {
+    if (!r.open) continue;
+    for (const f of requestMarkdown(top, r.dir)) {
+      if (f.unreadable) continue;
+      let t = null;
+      try {
+        t = read(top, `${r.dir}/${f}`);
+      } catch {
+        t = null;
+      }
+      if (typeof t === 'string') files.push([`${r.dir}/${f}`, t]);
+    }
+  }
+  for (const [file, text] of files) {
+    for (const h of phraseHits(text, matchers)) add('hint', 'phrase', `${file}:${h.line}`, '-', phraseMessage(h));
+  }
+}

package/src/v4/scope.js

@@ -44,6 +44,9 @@ const linked = (top, config) => [
   ...insideDocs(config).map((d) => String(d.file)).filter((f) => symlinkOn(top, clean(f))),
 ];
 
+// The docs that config lists, in the repo, that a symlink reaches (#238).
+export const linkedDocs = (top, config) => insideDocs(config).map((d) => clean(d.file)).filter((f) => symlinkOn(top, f));
+
 // Why config's root cannot be used, or null: the repository top is no spec root.
 export const rootProblem = (config) => (!outside(config.root) && ['.', ''].includes(clean(config.root))
   ? `.assuredloop/config.yaml: root: ${JSON.stringify(String(config.root))} is the repository top; give the spec folder, for example specs`
@@ -99,7 +102,16 @@ export function prefixOf(path, config) {
 // Every file of the working tree under `dir`, symlinks not followed.
 function walk(top, dir, out = []) {
   if (!existsSync(join(top, dir)) || !lstatSync(join(top, dir)).isDirectory()) return out;
-  for (const e of readdirSync(join(top, dir), { withFileTypes: true })) {
+  let entries;
+  try {
+    entries = readdirSync(join(top, dir), { withFileTypes: true });
+  } catch (e) {
+    // A folder under requests/ that cannot be read: al check reports it, as
+    // an unreadable record or current place (#238).
+    if (dir.startsWith('requests/')) return out;
+    throw e;
+  }
+  for (const e of entries) {
     if (e.name === '.git' || e.name === 'node_modules') continue;
     const p = dir ? `${dir}/${e.name}` : e.name;
     if (e.isDirectory()) walk(top, p, out);

package/src/v4/state.js

@@ -4,10 +4,10 @@
 import { readdirSync } from 'node:fs';
 import { join, posix } from 'node:path';
 import { parse } from 'yaml';
-import { read, recordPath, sha256 } from './base.js';
+import { exists, read, recordPath, sha256 } from './base.js';
 import { loadConfig, loadSchema } from './config.js';
 import { fileAt, filesAt, git } from './git.js';
-import { KINDS, groupOf, parseMarkdown } from './markers.js';
+import { KINDS, groupOf, lf, parseMarkdown } from './markers.js';
 import { frameOf, requirements, signedText } from './request-md.js';
 import { SIGNED } from './snapshot.js';
 import { SPEC, docsInScope, parseScopes, symlinkOn } from './scope.js';
@@ -67,7 +67,8 @@ export function loadState(top, rev = null) {
     ...adrFiles.map((f) => `${root}/adr/${f}`),
   ]) : null;
   const get = rev ? (p) => (atRev.has(p) ? atRev.get(p) : fileAt(top, rev, p)) : (p) => read(top, p);
-  const { scopes, lints } = parseScopes(docsInScope(top, config, rev), kinds);
+  const docs = docsInScope(top, config, rev);
+  const { scopes, lints } = parseScopes(docs, kinds);
   const spec = new Map((scopes.get(SPEC) ?? []).map((p) => [p.id, p]));
 
   const requests = new Map();
@@ -78,20 +79,30 @@ export function loadState(top, rev = null) {
     // The record is read now and parsed on first use (design.md 11): a check
     // that does not need an archived record never parses it.
     let text = null;
+    let readError = null;
     try {
       text = get(recordPath(name));
-    } catch {
+    } catch (e) {
       text = null;
+      readError = e.message.split('\n')[0];
     }
+    // read() gives null for a file it cannot read (EACCES, a folder): only a
+    // record that is not there at all has no error.
+    if (!rev && text == null && !readError && exists(top, recordPath(name))) readError = 'it is there, but it cannot be read as a file';
     let data;
+    let error = readError;
     const dataOf = () => {
       if (data !== undefined) return data;
       try {
         data = parse(text ?? 'null');
-      } catch {
+      } catch (e) {
+        data = null;
+        error = e.message.split('\n')[0];
+      }
+      if (!data || typeof data !== 'object' || Array.isArray(data)) {
+        if (text !== null && text !== undefined && !error) error = 'not a mapping';
         data = null;
       }
-      if (!data || typeof data !== 'object' || Array.isArray(data)) data = null;
       return data;
     };
     const specFile = `${dir}/spec.md`;
@@ -123,6 +134,8 @@ export function loadState(top, rev = null) {
     requests.set(name, {
       name, open, dir, md, specFile,
       get data() { return dataOf(); },
+      // Why a record that is there cannot be read, or null (#238).
+      get recordError() { dataOf(); return error; },
       get tier() { return tierOf(); },
       get spike() { return tierOf() === 'S' || /^##\s+Organized question\s*$/m.test(md); },
       // Whether the record's text names `x`, so that a reader parses only the
@@ -138,19 +151,33 @@ export function loadState(top, rev = null) {
   for (const n of archivedNames) if (!requests.has(n)) add(n, false);
 
   const adrs = new Map();
+  // The ADR files that are there but cannot be read (#238): R5 reports them.
+  const unreadableAdrs = [];
   for (const f of adrFiles) {
     const m = ADR_FILE.exec(f);
     if (!m) continue;
     const file = `${root}/adr/${f}`;
     const text = get(file);
-    if (text === null || text === undefined) continue;
+    if (text === null || text === undefined) {
+      if (!rev && exists(top, file)) unreadableAdrs.push(file);
+      continue;
+    }
     const paragraphs = parseMarkdown(text, file, { kinds }).paragraphs;
     const id = `ADR-${Number(m[1])}`;
     const status = /^\s*Status:\s*([a-z]+)/i.exec(text)?.[1].toLowerCase() ?? null;
     const head = paragraphs.find((p) => p.id === id) ?? null;
-    adrs.set(id, { id, file, status, body: adrBody(text), rest: head && adrRest(text, head), paragraphs, head });
+    // The status line that al knows: `Status: proposed`, `accepted` or
+    // `superseded by ADR-n` (#238), or by a list joined by commas and `and`,
+    // `ADR-11, ADR-12 and ADR-13` (#1). `by` is the ADRs that it names;
+    // `known` is whether it is the file's first line (#4). One parse gives
+    // both, so superseded-status and adr-status agree.
+    const s = /^(\s*)Status:[ \t]*(?:proposed|accepted|superseded[ \t]+by[ \t]+(ADR-\d+(?:(?:[ \t]*,[ \t]*(?:and[ \t]+)?|[ \t]+and[ \t]+)ADR-\d+)*))[ \t]*\r?(?:\n|$)/i.exec(text);
+    const by = [...new Set([...(s?.[2] ?? '').matchAll(/ADR-(\d+)/gi)].map((m) => `ADR-${Number(m[1])}`))];
+    const known = Boolean(s) && !/[\r\n]/.test(s[1]);
+    const marker = head && lf(text).split('\n')[head.line - 1];
+    adrs.set(id, { id, file, text, status, by, known, body: adrBody(text), rest: head && adrRest(text, head), paragraphs, head, marker });
   }
-  return { top, rev, config, kinds, root, get, scopes, lints, spec, requests, adrs };
+  return { top, rev, config, kinds, root, get, docs, scopes, lints, spec, requests, adrs, unreadableAdrs };
 }
 
 // The kind groups a check asks about.