IF Commons GitHub

AnyfsCli logical

0003Active

0003-anyfs-cli-logical · owner if · domain commons

Requirements

FR-001checkpassing

defineConfig MUST be a typed identity, parseConfig MUST check every mount (a name that is a word and unique, a place that parses), the defaults (concurrency from 1 to 64, a verify mode, a maximum object size of at least one byte) and the openers (one for each kind), and MUST give every problem it finds, not the first only.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/logical.test.ts

Proved by: anyfs-cli/suite/logical.test.ts

Written in: anyfs-cli/src/logical/config.ts

Tests: passed: suite/logical.test.ts parseConfig checks every mount, default and opener and gives every problem at once

Cited by: AnyFS command line, logical/config

FR-002checkpassing

A configuration MUST be written as code: its mounts MAY be marked read-only, and its kinds MUST be openers of stores that other libraries bring, so that a new backend is a line of the configuration and no change of the program.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/logical.test.ts

Proved by: anyfs-cli/suite/logical.test.ts

Written in: anyfs-cli/src/logical/config.ts

Tests: passed: suite/logical.test.ts a configuration carries read-only mounts and the openers other libraries bring

Cited by: AnyFS command line, logical/config

FR-003checkpassing

The verbs MUST run in a World of ports (open a place once for a run, a plain path as a root and an inner path, standard input and output as bytes, a local file, a small state) and in no other, so that they are tested with stores in memory.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/logical.test.ts

Proved by: anyfs-cli/suite/logical.test.ts

Written in: anyfs-cli/src/logical/world.ts

Tests: passed: suite/logical.test.ts the verbs run in the ports of a world and a store in memory is opened once

Cited by: AnyFS command line, logical/world

FR-004checkpassing

The capabilities a verb needs of a store MUST be asked at run time by viewable, sourceOf, movableOf and destOf, each of which MUST give nothing where a capability is missing, and missing MUST name the capabilities that are.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/logical.test.ts

Proved by: anyfs-cli/suite/logical.test.ts

Written in: anyfs-cli/src/logical/stores.ts

Tests: passed: suite/logical.test.ts a verb asks a store for the capabilities it needs and is told what is missing

Cited by: AnyFS command line, logical/stores

FR-005checkpassing

humanSize, modeText, table and drawTree MUST be pure: sizes below 1024 are bytes and above are K, M, G or T with one decimal where not whole; a mode is ten characters with the type first; a table pads every column but the last; a tree is drawn with branches.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/logical.test.ts

Proved by: anyfs-cli/suite/logical.test.ts

Written in: anyfs-cli/src/logical/format.ts

Tests: passed: suite/logical.test.ts sizes, modes, tables and trees are written the same way everywhere

Cited by: AnyFS command line, logical/format

FR-006checkpassing

unifiedDiff MUST give same for equal texts and the hunks of the shortest edit by the longest common subsequence, with three lines of context, for different ones, and MUST NOT compare two texts whose product of lines is over four million but say too-large.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/logical.test.ts

Proved by: anyfs-cli/suite/logical.test.ts

Written in: anyfs-cli/src/logical/diff.ts

Tests: passed: suite/logical.test.ts a diff is the shortest edit in hunks with context, and two huge texts are not compared

Cited by: AnyFS command line, logical/diff

FR-007checkpassing

matchingLines MUST find a literal text and never a pattern, with an option to ignore case; wildcard MUST read * as a run within a name and ? as one character; parseSizeTest MUST read +N, -N and N with the units K, M and G; looksLikeText MUST refuse bytes with a NUL in their first 8 KiB.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/logical.test.ts

Proved by: anyfs-cli/suite/logical.test.ts

Written in: anyfs-cli/src/logical/grep.ts

Tests: passed: suite/logical.test.ts text search is literal, wildcards and size tests follow their rules, and bytes with a NUL

Cited by: AnyFS command line, logical/grep

FR-008checkpassing

A verb MUST keep the fidelity of each operation of the POSIX view in a trail, and a failed operation MUST be written as its errno, its path and what the store said.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/logical.test.ts

Proved by: anyfs-cli/suite/logical.test.ts

Written in: anyfs-cli/src/logical/trail.ts

Tests: passed: suite/logical.test.ts a verb keeps the fidelity of each operation and writes a failure as its errno, its path an

Cited by: AnyFS command line, logical/trail

FR-009checkpassing

With --strict any step whose fidelity is a strict violation MUST end the verb with a problem E-STRICT, and with -v the steps that were not native MUST be written once each, so that nothing is pretended silently.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/logical.test.ts

Proved by: anyfs-cli/suite/logical.test.ts

Written in: anyfs-cli/src/logical/trail.ts

Tests: passed: suite/logical.test.ts strictness stops at what an emulation can lose, and verbosity writes each emulation once

Cited by: AnyFS command line, logical/trail

FR-010checkpassing

A run MUST end in one of four ways: with what it did, with a finding (exit findings), with a usage error (exit usage), or with an environment error (exit environment), and every problem MUST carry its code and the fix of the catalogue unless one is given.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/logical.test.ts

Proved by: anyfs-cli/suite/logical.test.ts

Written in: anyfs-cli/src/logical/outcomes.ts

Tests: passed: suite/logical.test.ts a run ends as what it did, a finding, a usage error or an environment error, with its code

Cited by: AnyFS command line, logical/outcomes

FR-011checkpassing

A plan MUST be written as its header, the counts of its actions by kind in the order a plan lists them, each action, what it would lose, the bytes to write and its hash, and at most two hundred actions are listed with the rest counted.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/logical.test.ts

Proved by: anyfs-cli/suite/logical.test.ts

Written in: anyfs-cli/src/logical/plans.ts

Tests: passed: suite/logical.test.ts a plan is written with its counts, each action and its hash, and a long plan is cut and co

Cited by: AnyFS command line, logical/plans

FR-012checkpassing

The refusals of the bridge MUST be written as the problems E-PLAN-REFUSED, E-PLAN-STALE and E-CONFLICTS, each with the sentence of the refusal, and a report MUST be written as its counts, its unguarded writes, each failure and its hash.

Enforced (check): .github: cd commons/anyfs-cli && bun run verify — suite/logical.test.ts

Proved by: anyfs-cli/suite/logical.test.ts

Written in: anyfs-cli/src/logical/plans.ts

Tests: passed: suite/logical.test.ts a refusal of the bridge is a problem of the catalogue with the sentence of the refusal

Cited by: AnyFS command line, logical/plans

Acceptance scenarios

  1. Given a configuration with two faults, When it is parsed, Then both are reported, per FR-001.
  2. Given a configuration with a read-only mount and an opener, When it is parsed, Then both are in the result, per FR-002.
  3. Given a world of memory stores, When a verb runs, Then it touches nothing outside the ports, per FR-003.
  4. Given a store without delete, When it is asked for as a destination, Then there is none and delete is named as missing, per FR-004.
  5. Given 1536 and a mode of 0644, When they are written, Then they are 1.5K and -rw-r--r--, per FR-005.
  6. Given two texts that differ on one line, When they are compared, Then one hunk shows it with its context, per FR-006.
  7. Given a text, a wildcard and a size test, When they are applied, Then they match as the rules say, per FR-007.
  8. Given a failed operation, When it is written, Then it holds the errno, the path and the problem kind, per FR-008.
  9. Given a trail with an emulated step of risk not-durable, When strictness is asked, Then there is a violation, and when verbosity is asked the step is a line, per FR-009.
  10. Given a usage ending and an environment ending, When their exits are read, Then they are usage and environment, per FR-010.
  11. Given a plan, When it is written, Then its last line is its hash, per FR-011.
  12. Given a stale refusal, When it is written, Then the problem is E-PLAN-STALE and names both hashes, per FR-012.

Out of scope

  • The backends that plug in through the configuration: their own libraries.
  • A mount of the stores as a file system (a WebDAV or NFS server, or FUSE): their own libraries.

Edge cases

  • Two texts too large to compare line by line: the result says so and does not stall, per FR-006.
  • A plan of more than two hundred actions: the rest are counted, per FR-011.
  • A configuration with several faults: every one is reported, per FR-001.

Assumptions

  • The libraries anyfs, anyfs-bridge, anyfs-posix, anyfs-ssh and Headless are on the branch that holds this library.

Open questions

  • None.

Key entities

  • AnyfsCli - the library.

Success criteria

SC-001success criterion

bun run verify in this folder passes.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

AnyFS command line, logical/config, logical/diff, logical/format, logical/grep, logical/outcomes, logical/plans, logical/stores, logical/trail, logical/world

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