@descent-vtt/spec-guard 0.11.0 → 0.12.0

package/dist/cites.d.ts

@@ -0,0 +1,192 @@
+/**
+ * `spec-guard cites`: the specs a codebase's comments cite, and whether each is
+ * still there and still in force. ADR-0017.
+ *
+ * A comment such as `// ADR-0011: the domain imports no infrastructure` is a
+ * claim about the codebase: that a decision exists, and governs this code.
+ * When the document is gone, or superseded, the comment sends the next reader
+ * to a decision that is not the one in force, and nothing notices - spec-graph
+ * reads only Markdown, and a run only the directives. This reads the other
+ * side: comment text, as ADR-0006's classifier finds it, for ids a project
+ * names.
+ *
+ * An id is found by a small scanner, never by a regular expression built from
+ * the template a project wrote: its literal text, a run of digits, and a word
+ * boundary on each side. The digits are a number, so `ADR-7`, `ADR-007` and a
+ * file called `0007-x.md` are one document.
+ */
+import { type Io } from './io.js';
+import type { CiteFamily, CitesReport, SpecStatus } from './types.js';
+/** Where the number goes, in an id template and in a file name. */
+export declare const NUMBER = "{n}";
+/** An id template, read: the text before the number, and the text after it. */
+export interface IdTemplate {
+    prefix: string;
+    suffix: string;
+}
+/**
+ * Why an id template cannot be used, or null.
+ *
+ * The text around `{n}` is literal, and it has to be there: `{n}` alone would
+ * make every number in every comment a citation. It may not be a digit where
+ * it meets the number, or the two would run together - `A1{n}` would never
+ * know where `A1` ended.
+ */
+export declare function citeIdError(template: string): string | null;
+/** An id template, read. Only ever given one `citeIdError` accepted. */
+export declare function parseIdTemplate(template: string): IdTemplate;
+/** A files template, read: the glob that finds the documents, and the name around the number. */
+export interface FilesTemplate {
+    /** The template with `{n}` read as `*`, taking in a `*` just after it: every path that could be a document. */
+    glob: string;
+    /** The file name before the number, which is literal. */
+    before: string;
+    /** The file name after the number, a glob of one segment, or empty. */
+    after: string;
+}
+/**
+ * Why a files template cannot be used, or null.
+ *
+ * The number is read from a document's file name, so `{n}` has to be in the
+ * last segment, and what comes before it there has to be literal: that is
+ * what says where in `0007-ledger.md` or `rfc-12.md` the number starts.
+ */
+export declare function citeFilesError(template: string): string | null;
+/** A files template, read. Only ever given one `citeFilesError` accepted. */
+export declare function parseFilesTemplate(template: string): FilesTemplate;
+/** A number as a comparable key: its digits without leading zeros, and `0` for none. */
+export declare function numberKey(digits: string): string;
+/**
+ * The number a document's path gives it under a files template - its digits
+ * as the file name spells them - or null when the path is not one of the
+ * template's documents.
+ *
+ * The whole path is matched against the glob, and then the file name is read:
+ * the literal text before the number, a run of digits as long as it goes, and
+ * a rest that the text after the number must match exactly. So `{n}-*.md`
+ * reads `0007` from `0007-x.md`, and nothing from `0007x.md` or `x-0007.md`.
+ */
+export declare function documentNumber(template: string): (relativePath: string) => string | null;
+/** One id found in text: which template, where, the number, and how it was written. */
+export interface Citation {
+    /** Index of the template in the list the scanner was given. */
+    family: number;
+    /** Offset of the id's first character. */
+    start: number;
+    end: number;
+    /** The number, as `numberKey` writes it. */
+    number: string;
+    /** The id as written. */
+    written: string;
+}
+/**
+ * Every id in a text, in order of position; the ids of one template before
+ * another's where two begin at one place.
+ *
+ * For each template: its literal prefix, then a run of digits, then its
+ * suffix, with no letter, digit or underscore running into either end - so
+ * `XADR-1` and `ADR-12a` are not `ADR-{n}` citations, and `ADR-12.` is. The
+ * whole text is read, once per template; which ids lie in a comment is
+ * `inComments`'s question.
+ */
+export declare function scanCitations(text: string, templates: readonly IdTemplate[]): Citation[];
+/**
+ * Whether an id is qualified by another owner, and so names that owner's
+ * document rather than one of this project's.
+ *
+ * `spec-core's ADR-0005`, `spec-graph ADR-0017`, `its ADR-0012` and
+ * `org/repo ADR-9` each cite a document in another repository, which only has
+ * the same number as one here by coincidence: read as this project's, it is a
+ * ghost when the number is not used here, and quietly the wrong document when
+ * it is. So the word just before an id - past one run of spaces - is read,
+ * and the id is another owner's when that word is a possessive (`'s`, `its`,
+ * `their`) or a name with a `-` or `/` inside it. `see ADR-7`, `per ADR-7`,
+ * `(ADR-7)`, `e.g. ADR-7` and `it's ADR-7` are this project's. What that
+ * costs is a hyphenated word used as an ordinary one, `re-read ADR-7`, which
+ * is read as a qualifier and not checked: a citation missed, rather than one
+ * reported that is not wrong.
+ *
+ * An id in a link is another owner's too: one just after a `/`, `#`, `=` or
+ * `?`, which is a path, an anchor or a query, or in a run of text holding
+ * `://`. `https://github.com/org/repo/blob/main/docs/adr/ADR-0042.md` names a
+ * document wherever that repository keeps it, and `docs/ADR-0099.html` a page
+ * built from one - neither is a document this template finds.
+ */
+export declare function qualified(text: string, start: number): boolean;
+/**
+ * The citations that lie wholly inside a comment. Both lists are in order of
+ * position, so one walk through each answers every question: the file is
+ * searched once for each template, rather than once per comment - which on a
+ * file of many comments and no citations would search to its end each time.
+ */
+export declare function inComments(citations: readonly Citation[], comments: ReadonlyArray<readonly [number, number]>): Citation[];
+export declare function isStale(status: string | undefined): boolean;
+/** A document of a family, as a citation needs to know it. */
+export interface CitedDocument {
+    /** Root-relative path. */
+    file: string;
+    /** The number as its file name spells it: `0007`. */
+    spelled: string;
+    title?: string;
+    status?: SpecStatus;
+}
+/** A family, ready to look up: its templates, and its documents by number. */
+export interface ResolvedFamily extends CiteFamily {
+    source: 'config' | 'derived';
+    template: IdTemplate;
+    documents: Map<string, CitedDocument[]>;
+}
+/**
+ * The documents a files template names, by number.
+ *
+ * Walked from the template's literal base, skipping what a run skips. The
+ * project's `exclude` is not applied: it says what no rule reads, and a
+ * document it leaves out of the rules still exists to be cited. A document
+ * that cannot be read is still a document, with no status.
+ */
+export declare function findDocuments(family: CiteFamily, root: string, io: Io, defaultSkips: boolean): Promise<Map<string, CitedDocument[]>>;
+/**
+ * The families a project's specs imply, when it names none.
+ *
+ * A directory of spec files whose names begin with a number is a numbered
+ * series, and a series whose documents all title themselves with one id and
+ * that same number - `# ADR-0007: ...` in `0007-x.md` - says how it is cited.
+ * Anything short of that is not guessed at: a series whose titles disagree, or
+ * do not begin with an id, gets a note saying to configure `cites`.
+ */
+export declare function deriveFamilies(documents: ReadonlyArray<{
+    file: string;
+    title?: string;
+}>): {
+    families: CiteFamily[];
+    notes: string[];
+};
+export interface CitesOptions {
+    /** Absolute root. */
+    root: string;
+    /** The spec globs: the files left out of the scan, and where families are derived from. */
+    patterns: readonly string[];
+    /** The families to look for; derived from the specs when absent. */
+    families?: readonly CiteFamily[];
+    /** Root-relative paths to read the comments of; the whole root when absent. */
+    paths?: readonly string[];
+    /** The project's exclusions, left out of the scan. */
+    exclude?: readonly string[];
+    /** Skip `.git`, `.hg`, `.svn` and `node_modules`, as a run does. */
+    defaultSkips?: boolean;
+    /** A stale citation is an error, and so is a file whose comments could not all be read. */
+    strict?: boolean;
+    io?: Io;
+}
+/** A configuration no answer can be trusted under: the report is not written, and the command exits 2. */
+export declare class CitesError extends Error {
+}
+/**
+ * Reads the comments of every source file in scope and reports each citation
+ * of a document that does not exist or is no longer in force.
+ *
+ * Throws `CitesError` when the answer could not be trusted: a family whose
+ * files match no document, which would make every citation of it a ghost.
+ */
+export declare function findCitations(options: CitesOptions): Promise<CitesReport>;
+//# sourceMappingURL=cites.d.ts.map

package/dist/cites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cites.d.ts","sourceRoot":"","sources":["../src/cites.ts"],"names":[],"mappings":"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"}