IF Commons GitHub

table

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-kanon-checker FR-010, 0001-kanon-checker FR-001

The table of a library that is Kanon (commons 0033-kanon FR-010): its units, each in one of the three layers or the library's own checking, as data a manifest declares and a program reads. This module holds the types of the table, the ranks of the layers and the decoder that reads a table from the kanon field of a manifest.

Parse, don't validate: a folder and a package name are branded types made only by their smart constructors (parseFolder, parsePackageName), and a Table holds nothing else, so a function that takes one never checks again. A unit is a sum, LayeredUnit | OwnUnit: a layered unit has a layer, an own unit (the library's tests and tools) has none and may import any file of the library by a relative path, so that no unit is both or neither. A unit with instances is one unit for each folder under it (a dialect, a surface, a model). What a unit may import of the library's other units is, by default, every unit of a layer above its own; where mayImport is given it is the exact list of the other units it may import. What it may import by package name is open where packages is absent, and exactly the listed packages where it is given.

import { decodeTable } from "@intellectual-frontiers/kanon";
const r = decodeTable({ package: "@intellectual-frontiers/x", units: [{ folder: "src/governance/", layer: "governance" }] });
r.kind; // "ok"

Source: commons/kanon/src/table.ts

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

Allowedtypeno test imports it
type Allowed = { readonly name: string; readonly subpaths: "any" | readonly string[] };

A package a unit may import, with the subpaths it may reach: any (the package and every entry of it), [] (the package's own entry only) or the listed subpaths.

decodeTablefunction
function decodeTable(input: unknown): Result<Table, string>

The table read from the kanon field of a manifest, or one sentence saying what is wrong with it (0033-kanon FR-010).

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

ExtensionRoletypeno test imports it
type ExtensionRole =
  | { readonly kind: "dialect"; readonly name: InstanceName; readonly instanceOf: FolderName }
  | { readonly kind: "plugin"; readonly noun: PluginNoun };

What an extension of another scope says it is, in its own table (0033-kanon FR-027): a dialect of a unit of the host, or a plugin with its noun.

Instancetypeno test imports it
type Instance =
  | { readonly kind: "folder"; readonly name: InstanceName; readonly instanceOf: FolderName; readonly folder: FolderName }
  | { readonly kind: "package"; readonly name: InstanceName; readonly instanceOf: FolderName; readonly package: PackageName };

One instance of a unit kind that a host declares (0033-kanon FR-019): a dialect, in a folder under the unit it is an instance of or in a package of its own. A sum, so that an instance is in a folder or in a package and never both; the package of a package instance is made by the family's rule.

LAYERSconst
const LAYERS: readonly ["governance", "logical", "physical"]

The layers of Kanon, from the top (0033-kanon FR-001).

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

Layertypeno test imports it
type Layer = (typeof LAYERS)[number];

One of the three layers: a closed union.

LayeredUnittypeno test imports it
type LayeredUnit = UnitBase & { readonly kind: "layered"; readonly layer: Layer };

A unit in one of the three layers.

OwnUnittypeno test imports it
type OwnUnit = UnitBase & { readonly kind: "own" };

The library's own checking (its tests, tools and examples): in no layer, and it may import any file of the library by a relative path.

Plugintypeno test imports it
type Plugin = {
  readonly noun: PluginNoun;
  readonly package: PackageName;
  readonly dependsOn: readonly PackageName[];
};

One plugin of a host (0033-kanon FR-020): a package of its own, named by the family's rule, with the plugins it declares it depends on.

RANKconst
const RANK: Readonly<Record<"governance" | "logical" | "physical", number>>

How far down a layer stands: Governance 1, Logical 2, Physical 3; a higher rank imports a lower (0033-kanon FR-007). A registry: one entry for each layer, which the compiler holds.

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

Tabletype
type Table = { /** The package's own name, which a unit uses to import another unit. */ readonly package: PackageNam… (827 characters)
type Table = {
  /** The package's own name, which a unit uses to import another unit. */
  readonly package: PackageName;
  readonly units: readonly Unit[];
  /** The naming rule of the packages that extend this library, where it has any (0033-kanon FR-021). */
  readonly family?: FamilyRule;
  /** The instances of its units that it declares (0033-kanon FR-019). */
  readonly instances: readonly Instance[];
  /** The plugins it declares (0033-kanon FR-020). */
  readonly plugins: readonly Plugin[];
  /** The host library this package extends, as a dialect or a plugin of it: a package is a host or an extension, never both (0033-kanon FR-020). */
  readonly extends?: PackageName;
  /** Its role in that host, where the host's family takes members of any scope (0033-kanon FR-027). */
  readonly role?: ExtensionRole;
};

The table of a library that is Kanon.

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

Unittypeno test imports it
type Unit = LayeredUnit | OwnUnit;

A unit of the table: a sum, so that a unit is a layered one or an own one and never both or neither.

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