IF Commons GitHub

imports

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-kanon-checker FR-012, 0001-kanon-checker FR-004, 0001-kanon-checker FR-002, 0001-kanon-checker FR-003

The import check of Kanon (commons 0033-kanon FR-004, FR-006, FR-011): given a table and the files of a library, every import of every file as data: which unit each file is in, and a finding for each import that does not follow the table. It reads every import, relative or by package name, because an import by package name is invisible to a check of relative imports; it resolves the library's own package name through exports, as Node and the compiler do. Lifted from the checks of commons/data and commons/headless, which each kept a table of their own.

Pure: it is given the files and the exports map and returns findings, which a program holds against a baseline. A file in no unit of the table is layers/unclassified, so that a surface or a dialect cannot appear without its row saying what it may import.

import { importFindings } from "@intellectual-frontiers/kanon";
const table = {
  package: "@intellectual-frontiers/x",
  units: [
    { folder: "src/governance/", layer: "governance" },
    { folder: "src/logical/", layer: "logical" },
  ],
} as const;
importFindings(table, [{ path: "src/governance/a.ts", text: 'import { b } from "@intellectual-frontiers/x/logical";\n' }], { "./logical": "./src/logical/mod.ts" }).map((f) => f.rule); // ["layers/above"]

Source: commons/kanon/src/imports.ts

8 of 16 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

allowedExternalfunctionno test imports it
function allowedExternal(allowed: readonly Allowed[], specifier: string): boolean

Whether a specifier is one of the packages a unit may import.

ExportsMaptype
type ExportsMap = Readonly<Record<string, string | { readonly [condition: string]: string }>>;

An exports map: each subpath to its target, a string or an object of conditions of strings.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

escapesRootfunctionno test imports it
function escapesRoot(from: string, specifier: string): boolean

Whether a relative specifier climbs out of the library's root from the file that imports it.

Findingtypeno test imports it
type Finding = {
  readonly rule: Rule;
  readonly file: string;
  readonly line: number;
  readonly message: string;
  readonly key: string;
};

A finding: its code, the file and line, one sentence, and a key that a baseline of findings can hold (<rule> <file> <about>).

familyOffunction
function familyOf(rule: Rule): "family" | "instances" | "kanon" | "layers" | "plugins"

The family of a code: the import check's or the model's; an exhaustive match, so that a code added to the union fails to compile here until it is placed.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

findingfunctionno test imports it
function finding(rule: Rule, file: string, line: number, message: string, about?: string | undefined): Finding

Make a finding with its key.

importFindingsfunction
function importFindings(table: Table, files: readonly SourceFile[], exportsMap: Readonly<Record<string, string | { readonly [condition: string]: string; }>>): readonly Finding[]

Every finding of the import check over a library's files (0033-kanon FR-011).

ParameterWhat it is
tablethe library's table
fileseach file of the library the check reads, its path from the library with / and its text
exportsMapthe exports of the library's package.json, each subpath (./logical) to its file (./src/logical/mod.ts)

Returns: the findings, in the order of the files

Imported by 35 tests of the run (35 passed, 0 failed): the library's results

Placedtypeno test imports it
type Placed = { readonly name: string; readonly unit: Unit };

The unit a file is in, as the table holds it: the unit's name (its folder, and for an instance the folder under it) and the row it comes from.

resolveImportfunctionno test imports it
function resolveImport(from: string, specifier: string): string

The path a relative specifier names, from the file that imports it.

RULE_SUMMARYconst
const RULE_SUMMARY: Readonly<Record<Rule, string>>

What each code means, in a sentence: a registry with an entry for every code of the closed union, which the compiler holds complete.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

RULESconst
const RULES: readonly ["layers/unclassified", "layers/relative", "layers/private", "layers/external", "layers/above", "layers/around", "layers/cycle", "instances/sibling", "instances/undeclared", "plugins/inverted", "plugins/undeclared", "plugins/contract", "family/name", "kanon/dropped", "kanon/kind", "kanon/annotation", "kanon/dangling", "kanon/relation-layer", "kanon/duplicate-id"]

The codes in one list, for a program that walks them.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

Ruletypeno test imports it
type Rule = | "layers/unclassified" | "layers/relative" | "layers/private" | "layers/external" | "layers/above… (434 characters)
type Rule =
  | "layers/unclassified"
  | "layers/relative"
  | "layers/private"
  | "layers/external"
  | "layers/above"
  | "layers/around"
  | "layers/cycle"
  | "instances/sibling"
  | "instances/undeclared"
  | "plugins/inverted"
  | "plugins/undeclared"
  | "plugins/contract"
  | "family/name"
  | "kanon/dropped"
  | "kanon/kind"
  | "kanon/annotation"
  | "kanon/dangling"
  | "kanon/relation-layer"
  | "kanon/duplicate-id";

The codes of this check (0033-kanon FR-011); kanon/dropped is the check of a model's annotations (dropped.ts).

SourceFiletype
type SourceFile = { readonly path: string; readonly text: string };

A file of the library: its path from the library's root with /, and its text.

Imported by 16 tests of the run (16 passed, 0 failed): the library's results

Specifiertypeno test imports it
type Specifier = { readonly line: number; readonly specifier: string };

An import of a file, with its line.

specifiersOffunction
function specifiersOf(text: string): readonly Specifier[]

Every import of a file's text, relative or by name: static, side-effect, re-export and dynamic import(), import type included.

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

unitOffunction
function unitOf(table: Table, path: string): Placed | undefined

The unit a file is in, from its path relative to the library with /; undefined where it is in none (layers/unclassified). The most specific folder wins.

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.