doc: add doc page for sqlite_lint

doc/TODO.txt

@@ -11,3 +11,7 @@ TODO: modified-timestamps
 
 TODO: generator-foreign-keys
 - add auto-foreign-key checking blocks to SaveXyz
+
+TODO: migration-structs
+- Right now, migrations are strings.  Could be a struct with "name", "up" and "down" fields
+- Adding a "down" operation enables handling newer DB versions with "down instead of error-out" for development (perhaps a flag)

doc/gas-stack.md

@@ -37,6 +37,31 @@
 - focus on testing
 - ORM-like affordances (but not actually using an ORM)
 
+## Vendoring vs Package Management vs In-Sourcing
+
+Dependencies are technical debt.  See [Loris Cro's talk about "How To Write Better Software with Zig"](https://www.youtube.com/watch?v=AEybWzeAkho).
+
+## Scaffolding
+
+Scaffolding is not boilerplate code, generated code, or library code.  It's *starter code* which is *intended to be modified* as needed.
+
+Library code is provided as a pre-made, off-the-shelf solution.  If your problem is exactly the one the library is intended to solve, and the library does a good job, you should use it.  Lots of big stuff is like this; nobody implements their own HTTP server or SQL engine as part of an application, because the domain is big, stable and standardized.  It makes perfect sense to use libraries for this.
+
+Boilerplate code and generated code (the latter being a common solution to the former) are usually indicators of bad abstractions.  If there's truly something that needs to be done exactly the same way by rote, every time, then there should be a reusable library for it-- or maybe you're even using the wrong programming language.
+
+Scaffolding isn't either of those, because scaffolding is intended to be *changed*.  It's just a starting point as you flesh out your ideas.
+
+Consider [this parable](https://rcrowley.org/2022/rails-django-parable.html) comparing Rails and Django on their initial setup and tutorial.  The analogy isn't perfect, but his claim is basically that the original Rails official tutorial left you with a tiny app with almost on code and a huge amount of functionality; but since all the functionality was invisible "magic" provided by Rails, as soon as you want something custom, you're nearly starting from scratch'.  By comparison, the Django tutorial produces a large amount of code which makes the abstractions explicit.  The author refers to all those extra lines of code as "footholds", from which you can start working.
+
+Scaffolding *begins* as generic boilerplate, but evolves as your application logic becomes more custom and requirements change.  One piece of scaffolded code might never change, because the scaffolding was good enough; another piece might be tweaked over time, as you add more to it (or remove parts you don't need); and another piece might change so much that no traces of the original scaffolding existed.  One app could contain all three of these.
+
+Scaffolding is intended to make "in-sourcing" your code easier, by getting you to something bare-bones-but-working faster.
+
+## Dynamic vs Static linking
+
+TODO: write about this and why it matters for the GAS stack
+
+
 ## SQLite and ROWID
 
 Tables must be EITHER:

doc/inspirations.txt

@@ -0,0 +1,7 @@
+- Urbit
+- BCHS stack
+- Ruby on Rails
+- Hasen Judi's "Data Storage and Retrieval From First Principles": https://hasen.substack.com/p/data-storage-and-retrieval
+- Matklad's "Basic Things": https://matklad.github.io/2024/03/22/basic-things.html
+- Zig, Andrew Kelley, Loris Cro
+- Max Tagher's "8 Lints for your Postgres Schema": https://mercury.com/blog/lints-for-postgres-schema

doc/rails-scaffolding-comparison.md

@@ -0,0 +1,41 @@
+See: https://guides.rubyonrails.org/v3.2/getting_started.html#getting-up-and-running-quickly-with-scaffolding
+
+# DB
+
+db/migrate/20100207214725_create_posts.rb:
+	- Migration to create the posts table in your database (your name will include a different timestamp)
+app/models/post.rb:
+	- The Post model
+test/unit/post_test.rb:
+	- Unit testing harness for the posts model
+test/fixtures/posts.yml:
+	- Sample posts for use in testing
+
+# Web
+
+config/routes.rb:
+	- Edited to include routing information for posts
+app/controllers/posts_controller.rb:
+	- The Posts controller
+app/views/posts/index.html.erb:
+	- A view to display an index of all posts
+app/views/posts/edit.html.erb:
+	- A view to edit an existing post
+app/views/posts/show.html.erb:
+	- A view to display a single post
+app/views/posts/new.html.erb:
+	- A view to create a new post
+app/views/posts/_form.html.erb:
+	- A partial to control the overall look and feel of the form used in edit and new views
+test/functional/posts_controller_test.rb:
+	- Functional testing harness for the posts controller
+app/helpers/posts_helper.rb:
+	- Helper functions to be used from the post views
+test/unit/helpers/posts_helper_test.rb:
+	- Unit testing harness for the posts helper
+app/assets/javascripts/posts.js.coffee:
+	- CoffeeScript for the posts controller
+app/assets/stylesheets/posts.css.scss:
+	- Cascading style sheet for the posts controller
+app/assets/stylesheets/scaffolds.css.scss:
+	- Cascading style sheet to make the scaffolded views look better

doc/sqlite-schema-rules-and-linter.md

@@ -0,0 +1,62 @@
+# SQLite Schema Rules and Linter
+
+The `sqlite_lint` subcommand enforces some rules that the GAS stack considers best-practices.
+
+All checks are enabled by default.  Disabling checks isn't recommended; many GAS stack methodologies assume your schema is designed in accordance with these rules, and will be less effective if you don't follow them.
+
+Currently the only way to disable them is setting an environment variable with the check name in capitals prefixed with `INPUT_`, e.g., `INPUT_REQUIRE_NOT_NULL=false` disables the `require_not_null` check. 
+
+```bash
+INPUT_REQUIRE_NOT_NULL=false gas sqlite_lint <path/to/schema.sql>  # `require_not_null` check will be skipped
+```
+
+## Available Checks
+
+This is a list of currently available checks.
+
+### `require_not_null`
+
+Enforce that all columns should be marked as `not null`, unless they are foreign keys.
+
+**Explanation**: 
+
+- Nulls are a common source of unexpected bugs, because they're usually an invalid state but often get created by mistake (e.g., you forgot to set a value).  Explicitly disabling nulls prevents such mistakes.
+- If the "natural zero value" is a valid value in your application and you explicitly need to distinguish it from "missing data", use an `has_xyz` or `is_xyz_valid` flag of some kind, rather than a nullable field.
+  - This is usually unnecessary, because the natural zero-values `0` and `""` (empty string) are usually sufficient to indicate "no value".  This is called a "sentinel value", or "in-band null value", because you don't need a special data type (null) to declare absence of data.
+- Foreign keys are exempt in this check, because `null` is a special value the integrity checker uses to say "this row has no related item".
+
+### `require_strict`
+
+Enforce that all tables should be marked as `strict`.
+
+**Explanation**:
+
+- By default, SQLite tables are very loose with what values they accept, and don't enforce any type checking.   "Strict" disables this "looseness", and enforces that inserted values match the stated type of the column.
+- "Strict" tables also limit to a small number of column types: `int`, `integer`, `real`, `text`, `blob` or `any`.
+  - To represent dates / times, use Unix epoch times in milliseconds, and convert to formatted dates (and timezones) only when displaying the value to a user.  This is the most portable and least bug-prone method to handle dates.
+
+See more about "strict" tables in SQLite's documentation: <https://sqlite.org/stricttables.html>
+
+### `forbid_int_type`
+
+Enforce that all columns should use `integer` type instead of `int`.
+
+**Explanation**:
+
+- This is an extension of "strict" tables, which allow two redundant integer types, `integer` and `int`.  This check standardizes the types further, permitting only `integer`.
+
+### `require_explicit_primary_key`
+
+Enforce that all tables must have a primary key.  If the primary key is `rowid`, it must be declared explicitly.
+
+**Explanation**: 
+
+- All tables need to have a primary key, and it should usually be `rowid`.  Declaring it explicitly improves the readability of the schema.
+
+### `require_indexes_for_foreign_keys`
+
+Enforce that columns referenced by foreign keys must have indexes.
+
+**Explanation**: 
+
+- Foreign keys are usually used for `join`s.  Joining on un-indexed columns is very slow.  Ensuring that all foreign-key-referenced columns have indexes will greatly improve the performance of database operations.