IF Commons GitHub

Acceptance utilities, sqlfs and sqlfind

0011Active

0011-acceptance · owner if · domain lang-sql

The language of both

FR-001checkpassing

The dialect sqlfs MUST be the common ground of SQL with the like-words GLOB and ILIKE, the units B, KB, MB, GB (1024 in each step) and S, M, H, D, W (seconds), and the functions now(), lower, upper, length, basename, dirname, regexp(text, pattern) and glob(text, pattern); the profile MUST be the queries of one table, files, with no join, no aggregate and no subquery, whose columns are name (text), path (text, relative to the root, with /), ext (text, without the dot), kind (f, d or l), size (int, bytes), mtime (timestamp, seconds since the epoch), mode (int), owner (text) and depth (int, 1 for a file in the root).

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/acceptance.test.ts: the dialect reads GLOB, ILIKE and the units, the profile is one table with no join, aggregate or subquery, the catalog types its columns, and a library registers the dialect and its functions

Proved by: lang-sql/suite/acceptance.test.ts

Tests: passed: suite/acceptance.test.ts the dialect reads GLOB, ILIKE and the units, the profile is one table with no join, aggreg

FR-002checkpassing

A query MUST be read, conformed to the profile, bound, typed and planned by aide (src/aide/); an error at any step MUST be an error value with a span and a sentence, and each utility MUST print it with the line and the caret.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/acceptance.test.ts: a query is read, conformed, bound, typed and planned, and an error of any step is an error value with a span that each utility prints with the line and a caret

Proved by: lang-sql/suite/acceptance.test.ts

Tests: passed: suite/acceptance.test.ts a query is read, conformed, bound, typed and planned, and an error of any step is an error

sqlfs

FR-003checkpassing

sqlfs MUST run a query over a file system given as an interface (a walk of entries with a name, a path, a kind, a size, a modification time, a mode, an owner and a depth), pruning a directory whose path and depth the filter shows to be out of reach where it can, and MUST give the same rows as the same query over an in-memory table of the entries; its command MUST read sqlfs [--root DIR] [--explain] [--format table|json|paths] 'SELECT ...'.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/acceptance.test.ts: sqlfs runs a query over a file system given as an interface, prunes the walk where the filter allows, gives what the in-memory table gives, and limits the rows

Proved by: lang-sql/suite/acceptance.test.ts

Tests: passed: suite/acceptance.test.ts sqlfs runs a query over a file system given as an interface, prunes the walk where the fil

sqlfind

FR-004checkpassing

sqlfind MUST compile a query to the argument list of a find command (never a shell string): the root, -mindepth and -maxdepth from depth, -type from kind, -name and -iname from name and ext and the equality and LIKE and GLOB of them, -path from path, -size in bytes (-size +Nc) from size, -newermt from mtime, -user from owner, -perm from mode, with -a, -o, ! and parentheses for AND, OR and NOT, and -print0; a condition that find cannot say MUST be left to the process, so that the rows are the same as those of sqlfs.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/acceptance.test.ts: sqlfind compiles a query to the arguments of find: depth, type, name patterns, path, size in bytes, time, owner and permissions are pushed, and what find cannot say is left to the process

Proved by: lang-sql/suite/acceptance.test.ts

Tests: passed: suite/acceptance.test.ts sqlfind compiles a query to the arguments of find: depth, type, name patterns, path, size

FR-005checkpassing

find MUST be given as a flavor, gnu or bsd: the GNU flavor reads the columns of the rows from -printf, the BSD flavor from -print0 and a lstat of each path in the process; the argument list MUST contain none of -exec, -execdir, -ok, -okdir, -delete, -fprint, -fprint0, -fprintf, -fls, whatever the query holds, and a test MUST prove it for hostile values.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/acceptance.test.ts: the flavors differ in what they read and push, and no argument list holds a flag that writes or runs, whatever the query holds

Proved by: lang-sql/suite/acceptance.test.ts

Tests: passed: suite/acceptance.test.ts the flavors differ in what they read and push, and no argument list holds a flag that writ

FR-006checkpassing

sqlfind --explain and sqlfs --explain MUST print the plan, what is pushed and what is residual; sqlfind --emit argv|shell MUST print the argument list as JSON or as one line quoted for a POSIX shell.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/acceptance.test.ts: --explain prints the plan, what is pushed and what is left, and --emit prints the command as JSON or as one line quoted for a shell

Proved by: lang-sql/suite/acceptance.test.ts

Tests: passed: suite/acceptance.test.ts --explain prints the plan, what is pushed and what is left, and --emit prints the command

Acceptance

FR-007checkpassing

For each query of a table of queries (the automated acceptance, AAT), over a fixture tree that a function builds the same way every time (names with spaces, newlines, quotes and glob characters, a symlink, a hidden directory, files of many sizes and times), the rows of sqlfs over the real directory, of sqlfs over the in-memory table, and of sqlfind through the real find of the system MUST be the same, ordered the same; the GNU flavor is run where the find of the system is GNU, and the argument lists of both flavors are held by golden files in acceptance/demos/, the BSD one being the only check of that flavor where the system has no BSD find.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/acceptance-aat.test.ts: for every query of the table, sqlfs over the disk, sqlfs over the entries the fixture is meant to have and sqlfind through the real find give the same rows

Proved by: lang-sql/suite/acceptance-aat.test.ts

Tests: passed: suite/acceptance-aat.test.ts for every query of the table, sqlfs over the disk, sqlfs over the entries the fixture is m

FR-008checkpassing

The operational acceptance (OAT) MUST prove, for each utility: the exit status (0 for a query that runs, 1 for a query that is wrong, 2 for a usage error, a root that is not a directory being one); that an unreadable directory does not stop the run and is reported as a warning, and that a symbolic link that loops is listed and not followed; that a result limit of the command (--max-rows, 10000 by default) and a depth limit (--max-depth, 64 by default) apply and the first is reported; that a hostile value in a query changes no more than its own condition; and that a tree of ten thousand entries is searched in under ten seconds.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/acceptance-aat.test.ts: each utility exits 0 for a query that runs, 1 for one that is wrong and 2 for a usage error; reports what it cannot read, lists a link that loops and does not follow it, limits depth and rows, leaves a hostile value in its own condition, and searches ten thousand entries in under ten seconds

Proved by: lang-sql/suite/acceptance-aat.test.ts

Tests: passed: suite/acceptance-aat.test.ts each utility exits 0 for a query that runs, 1 for one that is wrong and 2 for a usage erro

FR-009checkpassing

The user acceptance (UAT) MUST be a table of scenarios, each a sentence a person would say, the query that answers it and the paths it must give over the fixture; the demos MUST be the transcripts of the scenarios, generated into acceptance/demos/ by bun acceptance/demos.ts (which also writes, for each flavor of find, the command that sqlfind makes of each query of the automated acceptance), and a test MUST fail where a file is not what the utilities print.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/acceptance-aat.test.ts: the scenarios are answered as written by hand by both utilities, and the demo files are what the utilities print

Proved by: lang-sql/suite/acceptance-aat.test.ts

Tests: passed: suite/acceptance-aat.test.ts the scenarios are answered as written by hand by both utilities, and the demo files are wh

Out of scope

  • Joins, aggregates and a store other than the file system; publishing these utilities as packages.

Edge cases

  • A query whose filter folds to FALSE: no rows and no walk, per FR-003.
  • ORDER BY with LIMIT: done in the process, over the rows find gives, per FR-004.

Assumptions

  • The fixture has no entry younger than its own creation; times in the fixture are set with utimes.
  • find in this environment is GNU's; the BSD flavor is checked by golden argument lists and by a real BSD find only where one is the system's.

Open questions

  • None.

Key entities

  • Language - the dialect, profile and catalog both utilities share.
  • Fixture - the tree every acceptance runs over.
  • Scenario - a sentence, a query and the paths that answer it.

Success criteria

SC-001success criterion

Three independent ways of answering one query agree on a hostile tree.

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

Lang Sql

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