@timiagama/ecr 0.0.1 → 0.1.0

package/src/cli/diagnostic-reporter.ts

@@ -0,0 +1,344 @@
+/**
+ * Diagnostic Reporting
+ *
+ * Renders validation results for a terminal or for a machine. The pretty form
+ * groups diagnostics by document and prints a `path:line:column` prefix so an
+ * editor can jump to them; the JSON form is the same data unformatted, for CI
+ * and for tooling built on top of the CLI.
+ */
+
+import { showControlCharacters } from './safe-text.js';
+import { UNPARSABLE_DOCUMENT_RULE_ID } from '../per-document-visitor.js';
+import type { CorpusResult, Diagnostic, DiagnosticSeverity } from '../types.js';
+import type { CorpusStatisticsReport, DirectionCounts } from './corpus-statistics.js';
+
+/**
+ * Output formats the CLI can produce.
+ */
+export type ReportFormat = 'pretty' | 'json';
+
+/**
+ * A diagnostic together with the document it belongs to.
+ */
+interface LocatedDiagnostic {
+  /** Corpus-relative path of the document, or `(corpus)` when a diagnostic names no known document. */
+  readonly path: string;
+  /** The diagnostic itself. */
+  readonly diagnostic: Diagnostic;
+}
+
+/**
+ * Counts of diagnostics by severity.
+ */
+export interface SeverityTotals {
+  /** Diagnostics that make the corpus non-conforming. */
+  readonly errors: number;
+  /** Diagnostics that warrant attention but do not fail validation. */
+  readonly warnings: number;
+  /** Informational diagnostics. */
+  readonly infos: number;
+}
+
+/** Label used for a diagnostic whose URI matches no validated document. */
+const CORPUS_SCOPE_LABEL: string = '(corpus)';
+
+/**
+ * Formats corpus validation results and statistics for output.
+ */
+export class DiagnosticReporter {
+  /** The format to render in. */
+  private readonly format: ReportFormat;
+
+  /**
+   * Creates a reporter.
+   *
+   * @param format - The output format to produce
+   */
+  public constructor(format: ReportFormat) {
+    this.format = format;
+  }
+
+  /**
+   * Renders a corpus validation result.
+   *
+   * @param corpusResult - The result to render
+   * @param excludedPaths - Paths skipped as meta-documents or by ignore pattern
+   * @param notFollowedPaths - Links beneath the corpus root that were not followed
+   * @returns The text to write to standard output
+   */
+  public reportValidation(
+    corpusResult: CorpusResult,
+    excludedPaths: readonly string[],
+    notFollowedPaths: readonly string[],
+  ): string {
+    const located: readonly LocatedDiagnostic[] = this.collectDiagnostics(corpusResult);
+    const totals: SeverityTotals = this.countSeverities(located);
+
+    if (this.format === 'json') {
+      return JSON.stringify(
+        {
+          documents: corpusResult.documents.length,
+          excluded: excludedPaths,
+          notFollowed: notFollowedPaths,
+          totals,
+          diagnostics: located.map((entry: LocatedDiagnostic) => ({
+            path: entry.path,
+            ruleId: entry.diagnostic.ruleId,
+            severity: entry.diagnostic.severity,
+            message: entry.diagnostic.message,
+            ...(entry.diagnostic.range !== undefined
+              ? {
+                  // Positions are zero-based internally; editors are one-based.
+                  line: entry.diagnostic.range.start.line + 1,
+                  column: entry.diagnostic.range.start.character + 1,
+                }
+              : {}),
+          })),
+        },
+        null,
+        2,
+      );
+    }
+
+    return this.renderPretty(corpusResult, located, totals, excludedPaths, notFollowedPaths);
+  }
+
+  /**
+   * Renders a statistics report.
+   *
+   * @param statistics - The measured summary to render
+   * @param notFollowedPaths - Links beneath the corpus root that were not followed, and so not measured
+   * @returns The text to write to standard output
+   */
+  public reportStatistics(
+    statistics: CorpusStatisticsReport,
+    notFollowedPaths: readonly string[],
+  ): string {
+    if (this.format === 'json') {
+      return JSON.stringify({ ...statistics, notFollowed: notFollowedPaths }, null, 2);
+    }
+
+    const direction: DirectionCounts = statistics.referencesByDirection;
+    const links: readonly string[] = DiagnosticReporter.listNotFollowed(notFollowedPaths);
+    // A document the parser could not read contributes nothing to any of
+    // these numbers, so saying which ones, and that the numbers are therefore
+    // partial, is the difference between a measurement and a misreading.
+    const unparsable: readonly string[] =
+      statistics.unparsable.length === 0
+        ? []
+        : [
+            `  ${String(statistics.unparsable.length)} document(s) could not be parsed, ` +
+            'so they are not counted above:',
+            ...statistics.unparsable.map((path: string): string => `    ${path}`),
+            '  These statistics describe the rest of the corpus.',
+            '',
+          ];
+    const lines: readonly string[] = [
+      '',
+      '  Corpus structure',
+      '  ────────────────',
+      `  documents                      ${String(statistics.documents)}`,
+      `    with a References section    ${String(statistics.documentsWithReferences)}`,
+      `  sections                       ${String(statistics.sections)}`,
+      '',
+      `  unique DocIDs                  ${String(statistics.docIds)}`,
+      `  unique SectionIDs              ${String(statistics.sectionIds)}`,
+      '',
+      `  References entries             ${String(statistics.referenceEntries)}`,
+      `    authority                    ${String(direction.authority)}`,
+      `    constraint                   ${String(direction.constraint)}`,
+      `    contract                     ${String(direction.contract)}`,
+      `    dependency                   ${String(direction.dependency)}`,
+      '',
+      `  inline see/per references      ${String(statistics.inlineReferences)}`,
+      `    section-precise              ${String(statistics.sectionPreciseInlineReferences)}`,
+      '',
+      `  total edges                    ${String(statistics.totalEdges)}`,
+      '',
+      ...unparsable,
+      ...links,
+      ...(links.length > 0 ? [''] : []),
+    ];
+
+    return showControlCharacters(lines.join('\n'));
+  }
+
+  /**
+   * Counts the documents the parser could not read.
+   *
+   * @param corpusResult - The result being reported
+   * @returns How many documents produced an unparsable-document diagnostic
+   */
+  private static countUnparsable(corpusResult: CorpusResult): number {
+    return corpusResult.documents.filter((entry): boolean =>
+      entry.result.diagnostics.some(
+        (diagnostic: Diagnostic): boolean => diagnostic.ruleId === UNPARSABLE_DOCUMENT_RULE_ID,
+      ),
+    ).length;
+  }
+
+  /**
+   * Lists the links a walk did not follow, by name: unlike an exclusion,
+   * nobody asked for them to be skipped.
+   *
+   * @param notFollowedPaths - Links beneath the corpus root that were not followed
+   * @returns Lines to print; none when there are no such links
+   */
+  public static listNotFollowed(notFollowedPaths: readonly string[]): readonly string[] {
+    if (notFollowedPaths.length === 0) {
+      return [];
+    }
+
+    return [
+      `  ${String(notFollowedPaths.length)} link(s) not followed:`,
+      ...notFollowedPaths.map((path: string): string => `    ${path}`),
+    ];
+  }
+
+  /**
+   * Renders the human-readable form of a validation result.
+   *
+   * @param corpusResult - The result being rendered
+   * @param located - Diagnostics paired with their document paths
+   * @param totals - Severity counts across the corpus
+   * @param excludedPaths - Paths skipped during discovery
+   * @param notFollowedPaths - Links beneath the corpus root that were not followed
+   * @returns The text to write to standard output
+   */
+  private renderPretty(
+    corpusResult: CorpusResult,
+    located: readonly LocatedDiagnostic[],
+    totals: SeverityTotals,
+    excludedPaths: readonly string[],
+    notFollowedPaths: readonly string[],
+  ): string {
+    const lines: string[] = [''];
+
+    let currentPath: string | undefined = undefined;
+    for (const entry of located) {
+      if (entry.path !== currentPath) {
+        lines.push(`  ${entry.path}`);
+        currentPath = entry.path;
+      }
+
+      const position: string =
+        entry.diagnostic.range !== undefined
+          ? `${String(entry.diagnostic.range.start.line + 1)}:` +
+            String(entry.diagnostic.range.start.character + 1)
+          : '-';
+
+      lines.push(
+        `    ${position.padEnd(8)} ${entry.diagnostic.severity.padEnd(7)} ` +
+        `${entry.diagnostic.ruleId.padEnd(10)} ${entry.diagnostic.message}`,
+      );
+    }
+
+    if (located.length > 0) {
+      lines.push('');
+    }
+
+    const documentCount: string = String(corpusResult.documents.length);
+
+    // "checked" covers every document the command attempted, which is not the
+    // same as every document having been validated: one the parser could not
+    // read was attempted and counted, but nothing in it was validated. Those
+    // are then stated outright, and their errors are in the total already.
+    const unparsableCount: number = DiagnosticReporter.countUnparsable(corpusResult);
+    const unparsableNote: string =
+      unparsableCount > 0
+        ? ` ${String(unparsableCount)} document(s) could not be parsed.`
+        : '';
+
+    if (totals.errors === 0 && totals.warnings > 0) {
+      lines.push(
+        `  ${documentCount} document(s) checked, no errors, ` +
+        `${String(totals.warnings)} warning(s).${unparsableNote}`,
+      );
+    } else if (totals.errors === 0) {
+      lines.push(`  ${documentCount} document(s) checked, no errors.${unparsableNote}`);
+    } else {
+      lines.push(
+        `  ${documentCount} document(s) checked: ` +
+        `${String(totals.errors)} error(s), ${String(totals.warnings)} warning(s).${unparsableNote}`,
+      );
+    }
+
+    if (excludedPaths.length > 0) {
+      lines.push(`  ${String(excludedPaths.length)} path(s) excluded.`);
+    }
+
+    lines.push(...DiagnosticReporter.listNotFollowed(notFollowedPaths));
+
+    lines.push('');
+
+    // Every line here can carry text quoted from a document or a path from
+    // the disk, so the whole report is made safe to print in one place.
+    return showControlCharacters(lines.join('\n'));
+  }
+
+  /**
+   * Flattens per-document and corpus-wide diagnostics into one ordered list,
+   * grouped by document.
+   *
+   * A corpus-wide diagnostic still names the document it concerns — a
+   * duplicate DocID, an unresolved reference or a stale References title each
+   * belong to a specific file — so it is listed under that document, after the
+   * document's own diagnostics. Only a corpus-wide diagnostic whose URI matches
+   * no validated document falls back to the `(corpus)` label.
+   *
+   * @param corpusResult - The result to read
+   * @returns Diagnostics paired with the path they belong to, in document order
+   */
+  private collectDiagnostics(corpusResult: CorpusResult): readonly LocatedDiagnostic[] {
+    const located: LocatedDiagnostic[] = [];
+    const documentUris: ReadonlySet<string> = new Set(
+      corpusResult.documents.map((entry): string => entry.uri),
+    );
+
+    for (const entry of corpusResult.documents) {
+      for (const diagnostic of entry.result.diagnostics) {
+        located.push({ path: entry.uri, diagnostic });
+      }
+
+      for (const diagnostic of corpusResult.diagnostics) {
+        if (diagnostic.uri === entry.uri) {
+          located.push({ path: entry.uri, diagnostic });
+        }
+      }
+    }
+
+    for (const diagnostic of corpusResult.diagnostics) {
+      if (!documentUris.has(diagnostic.uri)) {
+        located.push({ path: CORPUS_SCOPE_LABEL, diagnostic });
+      }
+    }
+
+    return located;
+  }
+
+  /**
+   * Counts diagnostics by severity.
+   *
+   * @param located - The diagnostics to count
+   * @returns Totals per severity
+   */
+  private countSeverities(located: readonly LocatedDiagnostic[]): SeverityTotals {
+    let errors: number = 0;
+    let warnings: number = 0;
+    let infos: number = 0;
+
+    for (const entry of located) {
+      const severity: DiagnosticSeverity = entry.diagnostic.severity;
+
+      if (severity === 'error') {
+        errors += 1;
+      } else if (severity === 'warning') {
+        warnings += 1;
+      } else {
+        infos += 1;
+      }
+    }
+
+    return { errors, warnings, infos };
+  }
+}

package/src/cli/project-ignore.ts

@@ -0,0 +1,238 @@
+/**
+ * Project Ignore File
+ *
+ * `.ecrignore` holds a project's ignore patterns, so they need not be repeated
+ * with `--ignore` on every command. Like `.gitignore` it lives at the project
+ * root, which the CLI takes to be the working directory, as Prettier and
+ * ESLint do; it does not search upwards.
+ *
+ * Patterns use the same glob rules as `--ignore`, one per line, with blank
+ * lines and `#` comments allowed. They are relative to the working directory,
+ * whereas `--ignore` patterns are relative to the directory being linted.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+
+/** The file's name, at the project root. */
+export const PROJECT_IGNORE_FILENAME: string = '.ecrignore';
+
+/** What reading the project ignore file found. */
+export type ProjectIgnoreRead =
+  | { readonly kind: 'patterns'; readonly patterns: readonly string[] }
+  | { readonly kind: 'missing' }
+  | { readonly kind: 'unreadable'; readonly reason: string };
+
+/** The `.ecrignore` entry an installation needs, or why none can be made. */
+export type InstallExclusion =
+  | { readonly kind: 'pattern'; readonly pattern: string }
+  | { readonly kind: 'outside' }
+  | { readonly kind: 'invalid'; readonly reason: string };
+
+/**
+ * Characters that would change a destination's meaning if written into
+ * `.ecrignore` as a literal path: glob wildcards, and line breaks.
+ */
+const UNSAFE_PATH_CHARACTERS: RegExp = /[*?\r\n]/;
+
+/** A relative path that leaves the directory it is relative to. */
+const PARENT_PREFIX: RegExp = /^\.\.(?:[\\/]|$)/;
+
+/**
+ * How many names to try when creating the temporary file. A name collision
+ * needs 16 random hexadecimal digits to repeat, so one retry would do; a few
+ * cost nothing and keep a wedged directory from failing on chance alone.
+ */
+const TEMPORARY_NAME_ATTEMPTS: number = 5;
+
+/**
+ * Reads, parses and updates a project's `.ecrignore`.
+ */
+export class ProjectIgnoreFile {
+  /** Path of the `.ecrignore` file. */
+  private readonly path: string;
+
+  /**
+   * Creates a handle on the ignore file of a project.
+   *
+   * @param workingDirectory - The project root: the directory the command runs from
+   */
+  public constructor(workingDirectory: string) {
+    this.path = join(workingDirectory, PROJECT_IGNORE_FILENAME);
+  }
+
+  /**
+   * Reads the ignore file's patterns. A missing file is normal; one that
+   * exists but cannot be read is reported, not treated as empty.
+   *
+   * @returns The patterns, or that there is no file, or why it could not be read
+   */
+  public read(): ProjectIgnoreRead {
+    if (!existsSync(this.path)) {
+      return { kind: 'missing' };
+    }
+
+    try {
+      return { kind: 'patterns', patterns: ProjectIgnoreFile.parse(readFileSync(this.path, 'utf8')) };
+    } catch (error: unknown) {
+      return { kind: 'unreadable', reason: ProjectIgnoreFile.showReason(error) };
+    }
+  }
+
+  /**
+   * Adds a pattern unless the file already holds it, keeping everything else
+   * in the file exactly as it was. Creates the file if it does not exist.
+   *
+   * The new contents are written to a temporary file beside it, which then
+   * replaces it, so a write that fails part-way leaves the existing patterns
+   * untouched rather than truncated.
+   *
+   * @param pattern - The pattern to add
+   * @returns Whether the pattern was added or was already there
+   * @throws When the file cannot be read or replaced; it is then unchanged
+   */
+  public addPattern(pattern: string): 'added' | 'present' {
+    const existing: string = existsSync(this.path) ? readFileSync(this.path, 'utf8') : '';
+
+    if (ProjectIgnoreFile.parse(existing).includes(pattern)) {
+      return 'present';
+    }
+
+    const separator: string = existing === '' || existing.endsWith('\n') ? '' : '\n';
+    const temporaryPath: string = this.writeTemporaryFile(`${existing}${separator}${pattern}\n`);
+
+    try {
+      renameSync(temporaryPath, this.path);
+    } catch (error: unknown) {
+      ProjectIgnoreFile.removeQuietly(temporaryPath);
+
+      throw error;
+    }
+
+    return 'added';
+  }
+
+  /**
+   * Removes a temporary file this class created, ignoring any failure to do
+   * so: the error being reported is the write, and a leftover temporary file
+   * does not change what the user must do about it.
+   *
+   * @param path - Path of the temporary file
+   */
+  private static removeQuietly(path: string): void {
+    try {
+      rmSync(path, { force: true });
+    } catch {
+      // Nothing useful can be done, and nothing more needs saying.
+    }
+  }
+
+  /**
+   * Writes the replacement contents to a temporary file beside the ignore
+   * file, which this call creates itself.
+   *
+   * The name is unpredictable and the file is created exclusively, so nothing
+   * already at that path is opened: a link planted there, pointing anywhere on
+   * the disk, makes creation fail rather than be written through. That also
+   * means only a file this call created is ever removed.
+   *
+   * @param contents - The complete new contents of the ignore file
+   * @returns Path of the temporary file, which now holds those contents
+   * @throws When no temporary file could be created
+   */
+  private writeTemporaryFile(contents: string): string {
+    let lastError: unknown;
+
+    for (let attempt: number = 0; attempt < TEMPORARY_NAME_ATTEMPTS; attempt += 1) {
+      const candidate: string = `${this.path}.${randomBytes(8).toString('hex')}.tmp`;
+
+      try {
+        writeFileSync(candidate, contents, { encoding: 'utf8', flag: 'wx' });
+        return candidate;
+      } catch (error: unknown) {
+        if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+          // Something is already at that name. It is not this call's to
+          // read, write or remove: try another name.
+          lastError = error;
+          continue;
+        }
+
+        // Anything else means the name was free, so whatever is there now was
+        // created by the call that just failed, perhaps written only in part.
+        ProjectIgnoreFile.removeQuietly(candidate);
+        throw error;
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * Splits an ignore file into its patterns.
+   *
+   * @param text - The file's contents
+   * @returns Each pattern, trimmed, without blank lines or `#` comments
+   */
+  public static parse(text: string): readonly string[] {
+    return text
+      .split(/\r?\n/)
+      .map((line: string): string => line.trim())
+      .filter((line: string): boolean => line !== '' && !line.startsWith('#'));
+  }
+
+  /**
+   * Works out the exact `.ecrignore` pattern that excludes an installation
+   * directory, and nothing else.
+   *
+   * @param workingDirectory - The project root
+   * @param destination - The directory being installed into
+   * @returns The pattern; or that the destination lies outside the project and needs none; or why no safe pattern exists
+   */
+  public static readInstallExclusion(workingDirectory: string, destination: string): InstallExclusion {
+    const relativePath: string = relative(workingDirectory, destination);
+
+    if (relativePath === '') {
+      return {
+        kind: 'invalid',
+        reason: 'it is the working directory itself, and excluding it would exclude the whole project',
+      };
+    }
+
+    // Another drive on Windows gives an absolute path; a parent gives `..`.
+    if (isAbsolute(relativePath) || PARENT_PREFIX.test(relativePath)) {
+      return { kind: 'outside' };
+    }
+
+    const path: string = relativePath.replaceAll('\\', '/');
+
+    if (UNSAFE_PATH_CHARACTERS.test(path)) {
+      return { kind: 'invalid', reason: 'its name contains `*`, `?` or a line break, which .ecrignore would read as a pattern' };
+    }
+
+    if (path.startsWith('#')) {
+      return { kind: 'invalid', reason: 'its name starts with `#`, which .ecrignore would read as a comment' };
+    }
+
+    if (path !== path.trim()) {
+      return { kind: 'invalid', reason: 'its name starts or ends with a space, which .ecrignore would drop' };
+    }
+
+    return { kind: 'pattern', pattern: `${path}/**` };
+  }
+
+  /**
+   * Describes a file-system error briefly.
+   *
+   * @param error - What was thrown
+   * @returns The error's code, such as `EACCES`, or its message
+   */
+  public static showReason(error: unknown): string {
+    if (error instanceof Error) {
+      const code: unknown = (error as NodeJS.ErrnoException).code;
+      return typeof code === 'string' ? code : error.message;
+    }
+
+    return String(error);
+  }
+}

package/src/cli/safe-text.ts

@@ -0,0 +1,39 @@
+/**
+ * Terminal-Safe Text
+ *
+ * The CLI prints text it did not write: titles and headings quoted back from
+ * documents, and the paths of files it found. A terminal reads some characters
+ * as commands rather than as text — an escape sequence can clear the screen,
+ * move the cursor, recolour what is already there or overwrite a line — so a
+ * document could otherwise decide what the report of it appears to say.
+ *
+ * Anything printed as text is therefore written with those characters shown
+ * rather than obeyed. The JSON form needs no such treatment, because a
+ * consumer of it is not a terminal, and escaping there would change the data.
+ */
+
+/**
+ * Characters a terminal acts on rather than displays: the C0 controls apart
+ * from tab and newline, delete, the C1 controls, and the bidirectional
+ * formatting characters, which reorder the text around them.
+ */
+// eslint-disable-next-line no-control-regex -- Matching control characters is the point.
+const ACTED_ON_BY_TERMINALS: RegExp = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F‪-‮⁦-⁩]/g;
+
+/**
+ * Shows the characters a terminal would act on, rather than letting it act on
+ * them, writing each as the `\uXXXX` escape that names it.
+ *
+ * Tab and newline are left alone: the report is made of lines, and neither
+ * can misrepresent what it says.
+ *
+ * @param text - Text about to be printed to a terminal
+ * @returns The same text with every acted-on character shown
+ */
+export function showControlCharacters(text: string): string {
+  return text.replace(
+    ACTED_ON_BY_TERMINALS,
+    (character: string): string =>
+      `\\u${character.codePointAt(0)?.toString(16).padStart(4, '0') ?? ''}`,
+  );
+}