@conformetry/languages 0.0.1

package/dist/src/index.d.ts

@@ -0,0 +1,977 @@
+import { ConfigurationService } from '@conformetry/configuration';
+import { ConformetryDifference } from '@conformetry/core';
+import { ConformetryDifferenceLanguage } from '@conformetry/core';
+import { ConformetryDifferenceType } from '@conformetry/core';
+import { ConformetryLanguageValidator } from '@conformetry/core';
+import { DocumentValidationResult } from '@conformetry/core';
+import { LanguageValidatorDescriptor } from '@conformetry/core';
+import { MatchedInstance } from '@conformetry/configuration';
+import { Node } from 'typescript';
+import { PreparedValidationDocument } from '@conformetry/core';
+import { SourceFile } from 'typescript';
+import { ValidationFileResult } from '@conformetry/core';
+
+/** Arguments for building a missing-directory conformance error. */
+declare interface BuildMissingDirectoryErrorArguments {
+    readonly instanceDirectoryPath: string;
+    readonly templateDirectoryPath: string;
+}
+
+/** Arguments for building a missing-file conformance error. */
+declare interface BuildMissingFileErrorArguments {
+    readonly instanceFilePath: string;
+    readonly templateFilePath: string;
+}
+
+/** Arguments for turning a weight pair into a score. */
+export declare interface CalculateScoreArguments {
+    /** Combined weight of the requirements the instance failed. */
+    readonly failedWeight: number;
+    /** Combined weight of the requirements that were checked. */
+    readonly totalWeight: number;
+}
+
+/** Arguments for checking matched instances against the templates they matched. */
+export declare interface CheckInstanceFilesArguments {
+    readonly instances: MatchedInstance[];
+}
+
+/** What comparing the comments of two source files produced. */
+declare interface CommentComparison {
+    readonly missingComments: ExtractedComment[];
+    /** Number of template comments checked; each counts as one requirement. */
+    readonly totalWeight: number;
+}
+
+/** Arguments for walking one level of two markdown trees. */
+declare interface CompareChildrenArguments {
+    readonly instanceChildren: MarkdownNode[];
+    readonly templateChildren: MarkdownNode[];
+}
+
+/** The outcome of walking one level of two trees. */
+declare interface CompareChildrenResult {
+    readonly differences: MarkdownComparisonError[];
+    /** Template nodes the level weighed the instance against. */
+    readonly totalWeight: number;
+}
+
+/** Arguments for comparing the comments of two source files. */
+declare interface CompareCommentsArguments {
+    readonly instanceSourceFile: SourceFile;
+    readonly templateSourceFile: SourceFile;
+}
+
+/** Arguments for comparing two JSON values. */
+declare interface CompareJsonArguments {
+    readonly instanceValue: JsonValue;
+    readonly language: JsonComparisonLanguage;
+    readonly pathSegments?: JsonPathSegment[];
+    readonly templateValue: JsonValue;
+}
+
+/** Arguments for walking two syntax trees in parallel. */
+declare interface CompareTreeArguments {
+    readonly instanceNode: Node;
+    readonly templateNode: Node;
+}
+
+/**
+ * Weight a finding carries when it does not declare one.
+ *
+ * Right for any leaf requirement — a missing line, a missing comment — which
+ * is most of them. Only a finding standing in for a whole subtree needs to say
+ * otherwise.
+ */
+export declare const DEFAULT_ERROR_WEIGHT = 1;
+
+/**
+ * Owns construction and narrowing of structured conformance differences.
+ *
+ * Imported by every validator package so error shapes stay identical across
+ * languages, and by the file-existence pass for the file and directory
+ * categories.
+ */
+export declare class DifferencesModule {
+}
+
+/**
+ * Builds and narrows structured conformance differences.
+ *
+ * Every validator funnels through here so that error wording, the `fix`
+ * suggestion, and the location fields stay consistent across languages. The
+ * `resolve*` guards additionally narrow untrusted payloads — notably the JSON
+ * emitted by the Python validator bridge, whose fields cross a process
+ * boundary and cannot be trusted to match the TypeScript types.
+ */
+export declare class DifferencesService {
+    constructor();
+    /**
+     * Builds the error raised when a template directory has no counterpart in
+     * the instance tree. Carries no `language`, since a missing directory is not
+     * attributable to any one file format.
+     */
+    buildMissingDirectoryDifference(args: BuildMissingDirectoryErrorArguments): ConformetryDifference;
+    /**
+     * Builds the error raised when a template file has no counterpart in the
+     * instance tree. This is the one check that runs for every template file
+     * regardless of extension, so extension-less files such as `.gitignore` are
+     * covered too.
+     */
+    buildMissingFileDifference(args: BuildMissingFileErrorArguments): ConformetryDifference;
+    /**
+     * Narrows an untrusted value to a known error category, falling back to
+     * `"code"`. Falling back rather than throwing keeps one malformed error from
+     * failing an entire validation run.
+     */
+    resolveDifferenceType(value: unknown): ConformetryDifferenceType;
+    /**
+     * Narrows an untrusted value to a known error language, returning
+     * `undefined` when it matches none. Callers omit the field entirely rather
+     * than storing a bogus language.
+     */
+    resolveErrorLanguage(value: unknown): ConformetryDifferenceLanguage | undefined;
+}
+
+/**
+ * Score given to a document that imposes no requirements at all.
+ *
+ * An empty template asks for nothing, and nothing is exactly what the instance
+ * supplied, so it conforms perfectly. Scoring it zero would be arithmetic
+ * leaking into the answer: a run whose templates happen to be empty would fail
+ * every threshold while having found no fault with anything.
+ */
+export declare const EMPTY_TEMPLATE_SCORE = 1;
+
+/** A comment extracted from a source file, with its offset for ordering. */
+declare interface ExtractedComment {
+    readonly position: number;
+    readonly text: string;
+}
+
+/**
+ * What the existence pass found, and how much it asked for.
+ *
+ * The total counts every declared file, present ones included: a template
+ * asking for twenty files and getting nineteen has lost a twentieth of itself,
+ * which only the full denominator can say.
+ */
+export declare interface FilesCheckResult {
+    readonly fileResults: ValidationFileResult[];
+    /** One requirement per file the matched templates declare. */
+    readonly totalWeight: number;
+}
+
+/**
+ * Provides file and directory existence checking.
+ *
+ * Imported by `conformetry-validation`, which runs it before delegating to any
+ * language validator — a file that is absent cannot be compared.
+ */
+export declare class FilesModule {
+}
+
+/**
+ * Checks that every file a project's template declares actually exists.
+ *
+ * This runs before any language validator, and is the only check that covers
+ * *every* template file regardless of extension. A language validator only
+ * sees documents whose extension it claims, so files such as `.gitignore`,
+ * `.env.default`, and `pyproject.toml` were previously never checked at all —
+ * a project could delete them and still validate clean.
+ */
+export declare class FilesService {
+    private readonly configurationService;
+    private readonly errorsService;
+    constructor(configurationService: ConfigurationService, errorsService: DifferencesService);
+    /**
+     * Reports a path as a missing directory when the template entry lives under
+     * a directory that does not exist, and as a missing file otherwise.
+     *
+     * Reporting the absent directory once is more useful than reporting each of
+     * the twenty files inside it.
+     */
+    private buildMissingDifference;
+    /** Counts how many declared files one directory should hold. */
+    private countExpectedFiles;
+    /**
+     * Reports every file a matched instance's template requires but the instance
+     * lacks.
+     *
+     * Missing directories are collapsed to one finding each, so deleting a whole
+     * module reports the directory rather than each file within it.
+     */
+    checkInstanceFiles(args: CheckInstanceFilesArguments): FilesCheckResult;
+}
+
+/** What structurally comparing two JSON values produced. */
+export declare interface JsonComparison {
+    readonly differences: ConformetryDifference[];
+    /** Template nodes the walk weighed the instance against. */
+    readonly totalWeight: number;
+}
+
+/**
+ * Which validator is asking for the comparison.
+ *
+ * The walk is shared between JSON files and Jupyter notebooks, and the differences
+ * it emits must be attributed to whichever one raised them.
+ */
+declare type JsonComparisonLanguage = "json" | "python";
+
+/**
+ * Structurally compares two JSON documents.
+ *
+ * The template is treated as a **subset** requirement, not an exact match: the
+ * instance may add keys and array entries freely, but every key and value the
+ * template declares must be present. That is what makes a generated file
+ * editable after generation without immediately failing validation.
+ *
+ * Exported from this module so the Jupyter module can reuse it for
+ * notebooks, which are JSON documents, rather than duplicating the walk.
+ *
+ * The walk also counts what it asked for: every template node is one
+ * requirement, and a key with no counterpart costs the whole subtree beneath
+ * it, so dropping an object scores worse than dropping one of its scalars.
+ */
+export declare class JsonComparisonService {
+    private readonly scoringService;
+    constructor(scoringService: ScoringService);
+    /** Builds one structural error at a JSON path. */
+    private buildError;
+    /** Merges sibling comparisons into one. */
+    private combine;
+    /** Matches one required array entry against the instance array. */
+    private compareArrayItem;
+    /**
+     * Compares two arrays.
+     *
+     * Required scalars must appear somewhere in the instance array, order
+     * independent. For a required object, the instance entry that produces the
+     * fewest differences is taken as the intended match — an array entry has no key, so
+     * there is nothing better to match on.
+     */
+    private compareArrays;
+    /** Compares two objects, requiring every template key to be present. */
+    private compareObjects;
+    /**
+     * Adds the container's own requirement to what its members contributed, so a
+     * matched object weighs exactly what `countNodes` would have charged for it
+     * had it been missing.
+     */
+    private countContainer;
+    /** Counts a JSON value and every value nested inside it. */
+    private countNodes;
+    /** Renders a path as `scripts.build[0]` for error messages. */
+    private formatPath;
+    /** Returns whether a value is a plain JSON object. */
+    private isJsonObject;
+    /** Returns whether a value is a JSON scalar. */
+    private isJsonPrimitive;
+    /**
+     * Picks the candidate comparison that left the least of the template
+     * unaccounted for.
+     *
+     * Weighed by failed weight rather than error count: one finding standing in
+     * for a whole missing object is a worse match than two missing scalars.
+     */
+    private pickClosestMatch;
+    /**
+     * Compares a template value against an instance value, returning every way
+     * the instance fails to contain what the template requires.
+     */
+    compare(args: CompareJsonArguments): JsonComparison;
+}
+
+/**
+ * Provides the JSON language validator.
+ *
+ * `JsonComparisonService` is exported as well, because notebooks are JSON
+ * documents and the Jupyter module reuses the same structural walk.
+ */
+export declare class JsonModule {
+}
+
+/** One step of a JSON path: an object key or an array index. */
+declare type JsonPathSegment = number | string;
+
+/**
+ * Checks that a JSON or JSONC file contains everything its template declares.
+ *
+ * Parsing goes through `jsonc-parser` so a `tsconfig.json` with comments is
+ * read the same way TypeScript reads it.
+ */
+export declare class JsonService implements ConformetryLanguageValidator {
+    private readonly jsonComparisonService;
+    constructor(jsonComparisonService: JsonComparisonService);
+    readonly descriptor: LanguageValidatorDescriptor;
+    /** Reports every key or value the template requires and the instance lacks. */
+    validateDocument(document: PreparedValidationDocument): DocumentValidationResult;
+}
+
+/** Any JSON value, used when structurally comparing two documents. */
+export declare type JsonValue = boolean | JsonValue[] | null | number | string | {
+    [key: string]: JsonValue;
+};
+
+/**
+ * Provides the Jupyter notebook validator.
+ *
+ * Composes the JSON, markdown, and Python validators rather than
+ * reimplementing any of them — a notebook is all three formats at once.
+ */
+export declare class JupyterModule {
+}
+
+/**
+ * Reads the `.ipynb` format into something comparable.
+ *
+ * A notebook is JSON, but its meaning lives in the cells: markdown prose and
+ * Python code stored as line arrays. This service turns that back into text so
+ * the markdown and Python validators can work on it unchanged.
+ */
+export declare class JupyterNotebookService {
+    constructor();
+    /** Buckets each cell's text by kind, preserving notebook order. */
+    private groupSourcesByKind;
+    /** Narrows a cell's declared kind, defaulting to raw. */
+    private readCellKind;
+    /** Joins a cell's `source` line array back into text. */
+    private readCellSource;
+    /**
+     * Pairs template cells with instance cells of the same kind, in order.
+     *
+     * Cells are positional — a notebook has no cell identifiers — so the nth
+     * markdown cell is compared with the nth markdown cell. An instance may add
+     * cells at the end; it may not drop one the template declares.
+     */
+    pairCells(args: {
+        instanceNotebook: ParsedNotebook;
+        templateNotebook: ParsedNotebook;
+    }): {
+        missingCells: PairedCells[];
+        pairedCells: PairedCells[];
+    };
+    /**
+     * Parses notebook JSON, tolerating a malformed file by reporting no cells.
+     *
+     * A notebook that will not parse is reported by the structural pass, so
+     * throwing here would only duplicate that as a crash.
+     */
+    parseNotebook(content: string): ParsedNotebook;
+}
+
+/**
+ * Checks that a Jupyter notebook conforms to its template.
+ *
+ * A notebook is three formats at once, so this validator composes the three
+ * that already exist rather than reimplementing any: JSON for the envelope,
+ * markdown for prose cells, and the Python bridge for code cells. Validating a
+ * code cell through Python's own parser is what lets a notebook be re-run and
+ * reformatted without failing.
+ */
+export declare class JupyterService implements ConformetryLanguageValidator {
+    private readonly jsonComparisonService;
+    private readonly jupyterNotebookService;
+    private readonly markdownService;
+    private readonly pythonBridgeService;
+    constructor(jsonComparisonService: JsonComparisonService, jupyterNotebookService: JupyterNotebookService, markdownService: MarkdownService, pythonBridgeService: PythonBridgeService);
+    readonly descriptor: LanguageValidatorDescriptor;
+    /** Prefixes an error's message so a reader knows which cell it came from. */
+    private attributeToCell;
+    /** Reduces a notebook to the envelope keys that are compared structurally. */
+    private readEnvelope;
+    /** Validates one paired cell with the validator matching its kind. */
+    private validateCell;
+    /**
+     * Weighs a cell the notebook does not have.
+     *
+     * Measured by comparing the template cell against an empty instance, which
+     * is exactly what "none of this is present" means. Guessing a flat 1 instead
+     * would let a notebook drop a forty-line code cell for the same price as an
+     * empty one, and mixing in a line count would put a unit in the denominator
+     * that nothing else uses.
+     */
+    private weighMissingCell;
+    /** Reports every notebook difference: envelope, missing cells, cell contents. */
+    validateDocument(document: PreparedValidationDocument): DocumentValidationResult;
+}
+
+/**
+ * The one module a host imports to get every Language.
+ *
+ * Wiring the Languages individually is still possible — each has its own
+ * module — but a host almost always wants all of them, because the Fallback
+ * makes the text Language a floor under every run rather than an option.
+ */
+export declare class LanguagesModule {
+}
+
+/**
+ * Answers which Languages a run needs, and applies the Fallback.
+ *
+ * The Languages are injected rather than looked up by name, so this is the
+ * only place one has to be registered: adding a Language means adding it to
+ * `claimingLanguages` below, and its own descriptor says which extensions it
+ * claims. There is no second list of extensions to keep in step.
+ */
+export declare class LanguagesService {
+    private readonly jsonService;
+    private readonly jupyterService;
+    private readonly markdownService;
+    private readonly pythonService;
+    private readonly textService;
+    private readonly typescriptService;
+    constructor(jsonService: JsonService, jupyterService: JupyterService, markdownService: MarkdownService, pythonService: PythonService, textService: TextService, typescriptService: TypescriptService);
+    /**
+     * Every Language that claims extensions of its own, in report order.
+     *
+     * A method rather than a field, because the injected engines are assigned
+     * in the constructor and field initializers have already run by then.
+     *
+     * The text Language is deliberately absent. It is the Fallback, reached
+     * through `widenFallback` below, so it joins a run only when some extension
+     * needs it rather than on account of its own `.txt`.
+     */
+    private claimingLanguages;
+    /**
+     * The text Language, widened to also claim the extensions nothing else did.
+     *
+     * Widening the descriptor rather than special-casing the dispatch means the
+     * caller routes documents by extension exactly as it does for every other
+     * Language.
+     */
+    private widenFallback;
+    /**
+     * Resolves a validator for every extension in play.
+     *
+     * A Language is returned when the run holds at least one extension it
+     * claims, so a run over JSON alone never reports a TypeScript result it had
+     * nothing to say about. An extension nobody claims falls back to text,
+     * compared line by line, so no template file goes unchecked — silently
+     * skipping one would check less than the caller believes.
+     */
+    resolveValidators(args: ResolveValidatorsArguments): ConformetryLanguageValidator[];
+}
+
+/** A required markdown node the instance does not contain. */
+declare interface MarkdownComparisonError {
+    /** 1-based line in the instance where the node was expected. */
+    readonly instanceLine: number | undefined;
+    readonly nodeType: string;
+    readonly text: string;
+    /** Template nodes this one finding stands in for — the missing subtree. */
+    readonly weight: number;
+}
+
+/**
+ * Provides the markdown language validator.
+ *
+ * Imported by the Languages module, and by the Jupyter module, which reuses
+ * it for a notebook's markdown cells.
+ */
+export declare class MarkdownModule {
+}
+
+/**
+ * The subset of an mdast node this validator reads.
+ *
+ * Declared structurally rather than importing mdast's own types because only
+ * these fields participate in matching, and a narrow shape keeps the
+ * comparison honest about what it actually inspects.
+ */
+declare interface MarkdownNode {
+    readonly alt?: string;
+    readonly children?: MarkdownNode[];
+    readonly depth?: number;
+    readonly lang?: string;
+    readonly ordered?: boolean;
+    readonly position?: {
+        readonly end?: {
+            readonly line?: number;
+        };
+    };
+    readonly type: string;
+    readonly url?: string;
+    readonly value?: string;
+}
+
+/**
+ * Decides whether two markdown nodes are "the same node".
+ *
+ * Each node type has its own notion of identity: a heading is its depth plus
+ * its text, a link is its URL plus its text, a table is its column count. This
+ * is what lets a template require *a table with three columns* without
+ * dictating its contents.
+ */
+export declare class MarkdownNodesService {
+    constructor();
+    /**
+     * How to decide that two nodes of a given type are "the same node".
+     *
+     * A table rather than a switch so each rule stays its own small function —
+     * one branch per markdown type in a single method is unreadable, and the
+     * types that need no special rule fall through to a text comparison.
+     */
+    private readonly matchersByType;
+    /** Counts a table's columns from its first row. */
+    private readColumnCount;
+    /** Compares two optional string fields, treating absent as empty. */
+    private sameField;
+    /**
+     * Counts a node and every countable node beneath it.
+     *
+     * This is what a missing node costs. Comparison reports a vanished section
+     * once, but the template asked for the section and everything inside it, so
+     * weighing the finding by its subtree keeps a deleted table from scoring the
+     * same as a deleted heading.
+     *
+     * Skipped types are excluded on both sides of the fraction, so nodes the
+     * comparison never checks cannot dilute a score.
+     */
+    countSubtree(node: MarkdownNode): number;
+    /** Narrows a raw mdast child list to the nodes this validator understands. */
+    filterNodes(children: readonly unknown[]): MarkdownNode[];
+    /** Returns whether an instance node satisfies a template node. */
+    matches(args: {
+        instanceNode: MarkdownNode;
+        templateNode: MarkdownNode;
+    }): boolean;
+    /** Reads a node's children, or an empty list for a leaf. */
+    readChildren(node: MarkdownNode): MarkdownNode[];
+    /** Reads a node's rendered plain text. */
+    readText(node: MarkdownNode): string;
+}
+
+/**
+ * Checks that a markdown file contains every structure its template declares.
+ *
+ * Comparison is structural rather than textual: headings, code fences, links,
+ * and tables are matched as mdast nodes, so reformatting or reflowing prose
+ * does not fail validation while deleting a required section does.
+ */
+export declare class MarkdownService implements ConformetryLanguageValidator {
+    private readonly markdownNodesService;
+    private readonly markdownTreeService;
+    constructor(markdownNodesService: MarkdownNodesService, markdownTreeService: MarkdownTreeService);
+    /** GitHub-flavored so tables and task lists parse as their own node types. */
+    private readonly processor;
+    readonly descriptor: LanguageValidatorDescriptor;
+    /** Reports every markdown structure the template requires and the file lacks. */
+    validateDocument(document: PreparedValidationDocument): DocumentValidationResult;
+}
+
+/**
+ * Walks two markdown trees and reports what the template requires but the
+ * instance lacks.
+ *
+ * The walk is order-preserving but not position-locked: each template node is
+ * matched against any instance sibling, and the last match anchors the error
+ * location for whatever follows. A document may therefore add sections freely,
+ * as long as it still contains everything the template declares.
+ *
+ * The walk also counts what it asked for: every template node it weighs is one
+ * requirement, and a node with no counterpart costs its whole subtree.
+ */
+export declare class MarkdownTreeService {
+    private readonly markdownNodesService;
+    private readonly scoringService;
+    constructor(markdownNodesService: MarkdownNodesService, scoringService: ScoringService);
+    /** Describes a template node the instance does not contain. */
+    private buildError;
+    /**
+     * Matches a container node, then descends into it.
+     *
+     * Several instance nodes may match the container shape — two lists, say — so
+     * the one whose children satisfy the most of the template is chosen.
+     */
+    private compareContainer;
+    /** Matches a leaf node on its own identity, without descending. */
+    private compareLeaf;
+    /** Finds every instance sibling satisfying the template node. */
+    private findCandidates;
+    /** Compares one level of two trees, descending into containers. */
+    compareChildren(args: CompareChildrenArguments): CompareChildrenResult;
+}
+
+/**
+ * One notebook cell, in the subset of the `.ipynb` schema this validator uses.
+ *
+ * `source` is a list of lines with their newlines retained, which is how
+ * Jupyter stores it.
+ */
+declare interface NotebookCell {
+    readonly cell_type?: unknown;
+    readonly source?: unknown;
+}
+
+/** The cell kinds this validator understands. */
+declare type NotebookCellKind = "code" | "markdown" | "raw";
+
+/** A pair of template and instance cells of the same kind, in order. */
+declare interface PairedCells {
+    readonly index: number;
+    readonly instanceSource: string;
+    readonly kind: NotebookCellKind;
+    readonly templateSource: string;
+}
+
+/** A notebook reduced to the parts that are validated. */
+declare interface ParsedNotebook {
+    readonly cells: NotebookCell[];
+}
+
+/** The highest possible score: every template requirement is honoured. */
+export declare const PERFECT_SCORE = 1;
+
+/**
+ * Runs Python conformance checks through the Python interpreter.
+ *
+ * Python's syntax tree is only available from Python, so structural validation
+ * shells out to a small module shipped inside this package rather than
+ * approximating it with a line comparison. The subprocess is synchronous
+ * because callers are, and because one file's validation has nothing to
+ * overlap with.
+ */
+export declare class PythonBridgeService {
+    private readonly errorsService;
+    private readonly scoringService;
+    constructor(errorsService: DifferencesService, scoringService: ScoringService);
+    /**
+     * Directory holding the `python` package, resolved from this module rather
+     * than from the workspace root, so the bridge is found the same way whether
+     * conformetry runs from a checkout or from `node_modules`.
+     */
+    private readonly pythonRootPath;
+    /**
+     * Wraps a bridge failure as a reportable error rather than throwing.
+     *
+     * Weighed as a single failed requirement out of one: the file could not be
+     * checked at all, so claiming any particular proportion of it conforms would
+     * be an invention.
+     */
+    private buildBridgeError;
+    /** Reads the optional location fields, omitting any the bridge left out. */
+    private readLocations;
+    /** Narrows an untrusted numeric field from the bridge payload. */
+    private readNumber;
+    /** Narrows an untrusted string field from the bridge payload. */
+    private readString;
+    /** Reads the optional expected and actual values. */
+    private readValues;
+    /** Maps one snake_case bridge error onto the shared error shape. */
+    private toConformetryDifference;
+    /**
+     * Compares one Python source against its rendered template.
+     *
+     * A missing interpreter, a crashed bridge, or unreadable output are all
+     * reported as conformance differences: they mean this file could not be checked,
+     * which the run should surface, but they must not abort validation of every
+     * other file.
+     */
+    validatePythonSource(args: RunPythonBridgeArguments): DocumentValidationResult;
+}
+
+/**
+ * Provides the Python language validator.
+ *
+ * `PythonBridgeService` is exported as well, because a notebook's code cells
+ * are Python and the Jupyter module validates them through the same bridge.
+ */
+export declare class PythonModule {
+}
+
+/**
+ * Checks that a Python file declares everything its template requires.
+ *
+ * Comparison is structural, through Python's own `ast` module, so reformatting
+ * a file or reordering its declarations does not fail validation while
+ * deleting a required class or function does.
+ */
+export declare class PythonService implements ConformetryLanguageValidator {
+    private readonly pythonBridgeService;
+    constructor(pythonBridgeService: PythonBridgeService);
+    readonly descriptor: LanguageValidatorDescriptor;
+    /** Reports every declaration and comment the template requires. */
+    validateDocument(document: PreparedValidationDocument): DocumentValidationResult;
+}
+
+/** Arguments for resolving the Languages one validation run needs. */
+export declare interface ResolveValidatorsArguments {
+    /**
+     * Every distinct file extension the run's templates declare, including the
+     * leading dot. Extensions no Language claims are routed to the Fallback.
+     */
+    readonly extensions: string[];
+}
+
+/** Arguments for one bridge invocation. */
+declare interface RunPythonBridgeArguments {
+    readonly filename: string;
+    readonly instance: string;
+    /** Template source, already rendered on the TypeScript side. */
+    readonly template: string;
+}
+
+/**
+ * Owns the conformance arithmetic every validator and host would otherwise
+ * repeat: what a finding weighs, and what a weight pair scores.
+ */
+export declare class ScoringModule {
+}
+
+/**
+ * Turns weights into conformance scores.
+ *
+ * The arithmetic is small but it is the same arithmetic in seven places — one
+ * per language package, plus the file-existence pass and the run aggregate —
+ * and it has two edge cases worth getting right once: the default weight of a
+ * finding that declares none, and an empty template whose denominator is zero.
+ */
+export declare class ScoringService {
+    constructor();
+    /**
+     * Returns the share of the checked requirements the instance honoured, from
+     * 0 to 1.
+     *
+     * Clamped at both ends. A validator that double-counts an overlapping
+     * requirement could otherwise report a failed weight above the total and
+     * produce a negative score, which would read as a much worse instance than
+     * one that is simply entirely wrong.
+     */
+    calculateScore(args: CalculateScoreArguments): number;
+    /** Adds up what a set of findings costs, defaulting each to its own weight. */
+    sumWeights(differences: readonly WeightedFinding[]): number;
+}
+
+/**
+ * Provides the text validator service.
+ */
+export declare class TextModule {
+}
+
+/**
+ * Checks that a text file contains every line its template requires.
+ *
+ * Matching is duplicate-aware: a template line that appears twice must appear
+ * twice in the instance. Order is not enforced, so a file may add lines
+ * anywhere — the template is a lower bound, not an exact specification.
+ */
+export declare class TextService implements ConformetryLanguageValidator {
+    constructor();
+    readonly descriptor: LanguageValidatorDescriptor;
+    /** Counts how many times each line occurs, for duplicate-aware matching. */
+    private countLines;
+    /** Finds template lines the instance does not supply often enough. */
+    private findMissingLines;
+    /**
+     * Reports every template line missing from the instance.
+     *
+     * Every template line is one requirement, blank ones included: this
+     * validator matches them literally, so a blank line the instance does not
+     * supply is a real miss and counting it keeps the denominator honest.
+     */
+    validateDocument(document: PreparedValidationDocument): DocumentValidationResult;
+}
+
+/** What comparing two syntax trees produced. */
+declare interface TreeComparison {
+    readonly differences: TypescriptComparisonError[];
+    /** Number of template nodes the walk weighed the instance against. */
+    readonly totalWeight: number;
+}
+
+/**
+ * Checks that a file carries the comments its template requires, in order.
+ *
+ * Order matters here in a way it does not for declarations: the section
+ * markers (`🏗 Dependency Injection`, `🔏 Private Methods`, …) are comments,
+ * and a file that has them all but in the wrong order has not adopted the
+ * layout. Matching is therefore a subsequence check, not a set check.
+ */
+export declare class TypescriptCommentsService {
+    constructor();
+    /**
+     * Reports each template comment absent from the instance, or present but
+     * out of order relative to the comments before it.
+     *
+     * Every template comment is one requirement, whatever its length: a section
+     * marker is a marker. That is reported alongside the misses so a document
+     * whose comments are all present still contributes them to its score.
+     */
+    compareComments(args: CompareCommentsArguments): CommentComparison;
+    /**
+     * Collects every comment in a source file, in source order.
+     *
+     * Walks down to individual tokens and reads the trivia preceding each one.
+     * Every comment precedes some token, including the closing brace of a class,
+     * which is what makes this complete.
+     *
+     * Two simpler approaches fail here. Reading leading and trailing ranges off
+     * *statement* nodes misses any comment bordering no node — notably the
+     * section markers between the last class member and the closing brace, where
+     * `🔏 Private Methods` and `🌎 Public Methods` live in an otherwise empty
+     * service; those markers were silently unenforceable. Scanning the raw token
+     * stream instead loses sync on template literals, because a substitution's
+     * closing brace needs an explicit re-scan, and everything after the first
+     * template substitution is mis-tokenized.
+     */
+    extractComments(sourceFile: SourceFile): ExtractedComment[];
+}
+
+/** A declaration the template requires and the instance does not contain. */
+declare interface TypescriptComparisonError {
+    /** Offset in the instance file to anchor the error at, when known. */
+    readonly instancePosition: number | undefined;
+    /** Syntax-kind label, e.g. `ClassDeclaration`. */
+    readonly kindLabel: string;
+    /** The node's key — an import specifier, a member name — when it has one. */
+    readonly nodeKey: string | undefined;
+    /** Offset in the rendered template where the requirement is declared. */
+    readonly templatePosition: number | undefined;
+    /** Template nodes this one finding stands in for — the missing subtree. */
+    readonly weight: number;
+}
+
+/**
+ * Provides the TypeScript language validator.
+ *
+ * Split into node keying, tree walking, and comment comparison so each concern
+ * stays independently testable — the same decomposition the previous
+ * conformance tool used.
+ */
+export declare class TypescriptModule {
+}
+
+/**
+ * Derives a stable identity for a syntax node.
+ *
+ * Matching by key rather than by position is what lets a file reorder its
+ * members, or add new ones, without failing validation: an import is
+ * identified by its module specifier, a member by its name, a decorator by its
+ * dotted callee. Nodes with no meaningful key fall back to matching on syntax
+ * kind alone.
+ */
+export declare class TypescriptNodesService {
+    constructor();
+    /** Builds a dotted name such as `Nest.Injectable` from a callee expression. */
+    private buildDottedName;
+    /** Returns whether a value looks like a syntax node. */
+    private isNode;
+    /** Keys a decorator by its callee, so `@Injectable()` matches `@Injectable`. */
+    private readDecoratorKey;
+    /** Keys an export by its module specifier, when it re-exports one. */
+    private readExportKey;
+    /**
+     * Keys a call statement by its callee plus its first literal argument, so
+     * two `describe("...")` blocks are told apart by their subject.
+     */
+    private readExpressionStatementKey;
+    /** Keys an import by its module specifier. */
+    private readImportKey;
+    /** Reads a literal's text, for nodes that are themselves a value. */
+    private readLiteralKey;
+    /** Reads a declaration's own name, when it has one. */
+    private readNamedKey;
+    /**
+     * Counts a node and everything beneath it.
+     *
+     * This is what a missing declaration costs. Comparison reports a vanished
+     * class once, but the template asked for the class *and* every member inside
+     * it, so weighing that finding by its subtree is what keeps a deleted class
+     * from scoring the same as a deleted import.
+     */
+    countSubtree(node: Node): number;
+    /** Reads a node's direct children, skipping the end-of-file token. */
+    readChildren(node: Node): Node[];
+    /**
+     * Reads a node's identity, or `null` when it has none.
+     *
+     * A `null` key means the node can only be matched by syntax kind — which is
+     * why an anonymous statement is satisfied by any statement of that kind.
+     */
+    readKey(node: Node): null | string;
+    /** Reads a node's syntax-kind label, for error messages. */
+    readKindLabel(node: Node): string;
+}
+
+/**
+ * Checks that a TypeScript file declares everything its template requires.
+ *
+ * Two independent checks run over the same parse: the syntax tree, which
+ * verifies imports, decorators, classes, and members exist; and the comments,
+ * which verify the section markers appear in the prescribed order.
+ */
+export declare class TypescriptService implements ConformetryLanguageValidator {
+    private readonly typeScriptCommentsService;
+    private readonly typeScriptTreeService;
+    constructor(typeScriptCommentsService: TypescriptCommentsService, typeScriptTreeService: TypescriptTreeService);
+    readonly descriptor: LanguageValidatorDescriptor;
+    /** Parses source text, choosing the dialect from the filename. */
+    private parseSourceFile;
+    /** Converts a source offset into a 1-based line and column. */
+    private readLocation;
+    /** Compares the comments and describes each missing section marker. */
+    private validateComments;
+    /** Compares the syntax trees and describes each missing declaration. */
+    private validateStructure;
+    /**
+     * Reports every declaration and comment the template requires.
+     *
+     * The two passes weigh independent things — structure counts syntax nodes,
+     * comments count section markers — so their totals add rather than one
+     * subsuming the other.
+     */
+    validateDocument(document: PreparedValidationDocument): DocumentValidationResult;
+}
+
+/**
+ * Walks two syntax trees in parallel and reports what the template requires
+ * but the instance does not contain.
+ *
+ * The template is a **structural subset** requirement: every declaration it
+ * makes must exist somewhere in the instance, but the instance may add
+ * anything and may order its members freely.
+ *
+ * The walk also counts what it asked for. Every template node visited is one
+ * requirement, and a node with no counterpart costs its whole subtree, so the
+ * weight of a finding is proportional to how much of the template went
+ * missing rather than to how many findings were printed.
+ */
+export declare class TypescriptTreeService {
+    private readonly scoringService;
+    private readonly typeScriptNodesService;
+    constructor(scoringService: ScoringService, typeScriptNodesService: TypescriptNodesService);
+    /** Describes a template node with no instance counterpart. */
+    private buildError;
+    /**
+     * Descends into whichever candidate explains the template best.
+     *
+     * Several instance nodes can share a key or kind — two methods with the same
+     * name on different classes, say — so the one leaving the least of the
+     * template unaccounted for is taken as the intended match.
+     *
+     * Weighed by failed weight rather than by error count: one finding standing
+     * in for a whole missing class is a worse match than two missing imports,
+     * and counting findings would have picked the wrong one.
+     */
+    private compareBestCandidate;
+    /** Matches one template child against the instance's children. */
+    private compareChild;
+    /** Compares one level of two trees, descending into every match. */
+    compareTree(args: CompareTreeArguments): TreeComparison;
+}
+
+/**
+ * Anything that carries a weight.
+ *
+ * Deliberately narrower than `ConformetryDifference`: a language package weighs its
+ * own internal findings before they are ever described as conformetry differences,
+ * and requiring the full error shape would force it to build messages just to
+ * count.
+ */
+export declare interface WeightedFinding {
+    readonly weight?: number;
+}
+
+export { }