Docs for 2.3

CONTRIBUTING.md

@@ -15,7 +15,8 @@ example README, package README and user-facing command text.
   `from` and `to`; never paste sample YAML into a page. `<Template>` shows
   part of a file in `ci-templates/` the same way. What a sample uses comes from resolving it; never hand-write it.
 - Facts the code knows (settings, defaults, connector facts, error codes,
-  document fields, CLI commands) are rendered by components in
+  document fields, CLI commands, what each pack does with intent, and the
+  published standards' files) are rendered by components in
   `components/reference/`. Change the code, not the page.
 - Every page belongs to one of seven areas, each a folder whose `meta.json`
   says `"root": true`. A folder in brackets, such as `how-to/(build)/`,

app/blocks.css

@@ -205,3 +205,55 @@ figure[data-kind="run"] .line.cmd::before {
   color: var(--brand-signal);
   user-select: none;
 }
+
+/* A value still REPLACE_ME in a kit's file (components/replace-me.tsx): a
+   dashed underline and its note's number mark it, not colour alone, with a
+   light tint. Its tooltip sits above the page; touch screens, which cannot
+   hover, show the notes below the block instead. */
+.replace-me {
+  text-decoration: underline dashed 1px;
+  text-underline-offset: 3px;
+  background: color-mix(in srgb, var(--docs-link) 12%, transparent);
+  border-radius: 2px;
+  cursor: help;
+}
+.replace-me::after {
+  content: attr(data-note);
+  margin-left: 0.15em;
+  font-size: 0.7em;
+  vertical-align: super;
+  line-height: 0;
+}
+.replace-me:focus-visible {
+  outline: 2px solid var(--docs-link);
+  outline-offset: 2px;
+}
+.replace-me-tip {
+  position: fixed;
+  z-index: 60;
+  max-width: min(24rem, calc(100vw - 16px));
+  padding: 0.6rem 0.75rem;
+  border: 1px solid var(--color-fd-border);
+  border-radius: 0.5rem;
+  background: var(--color-fd-popover);
+  color: var(--color-fd-popover-foreground);
+  box-shadow: 0 6px 20px rgb(0 0 0 / 0.18);
+  font-size: 0.85rem;
+  line-height: 1.5;
+}
+.replace-me-line {
+  display: block;
+  margin-top: 0.3rem;
+}
+.prose .replace-me-notes {
+  display: none;
+  font-size: 0.9rem;
+}
+.replace-me-where {
+  color: var(--color-fd-muted-foreground);
+}
+@media (hover: none), print {
+  .prose .replace-me-notes {
+    display: block;
+  }
+}

app/content.css

@@ -219,3 +219,9 @@ pre code > .line {
   height: 0;
   scroll-margin-top: 7rem;
 }
+
+/* Where to find a field's value, and a suggestion (components/reference/field-rows.tsx): each on a line of its own. */
+.field-help {
+  display: block;
+  margin-top: 0.3rem;
+}

ci-templates/azure-devops/azure-pipelines.yml

@@ -33,7 +33,7 @@ stages:
               version: 22.x
           # An exact version: change it when you upgrade, as
           # https://docs.ingestron.io/docs/how-to/upgrade#choose-the-version-you-run says.
-          - script: npm install -g ingestron@2.2.0
+          - script: npm install -g ingestron@2.3.0
             displayName: Install Ingestron
           - script: ingestron check
             displayName: ingestron check

ci-templates/azure-devops/ingestron-check.yml

@@ -15,7 +15,7 @@ steps:
       version: 22.x
   # An exact version: change it when you upgrade, as
   # https://docs.ingestron.io/docs/how-to/upgrade#choose-the-version-you-run says.
-  - script: npm install -g ingestron@2.2.0
+  - script: npm install -g ingestron@2.3.0
     displayName: Install Ingestron
   - script: ingestron check
     displayName: ingestron check

ci-templates/github-actions/deploy.yml

@@ -29,7 +29,7 @@ jobs:
       - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
-      - run: npm install -g ingestron@2.2.0
+      - run: npm install -g ingestron@2.3.0
       - run: ingestron check
 
   build:

ci-templates/github-actions/ingestron-check.yml

@@ -18,5 +18,5 @@ jobs:
       - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: 22
-      - run: npm install -g ingestron@2.2.0
+      - run: npm install -g ingestron@2.3.0
       - run: ingestron check

components/mdx.tsx

@@ -23,7 +23,20 @@ import { ContractUseTable } from "@/components/reference/contract-use";
 import { PackCapabilities } from "@/components/reference/pack-capabilities";
 import { DefaultLayers, PackNaming } from "@/components/reference/pack-defaults";
 import { SamplesCatalogue } from "@/components/reference/samples-catalogue";
-import { ContractFields, DocumentFields } from "@/components/reference/document-fields";
+import {
+  ContractFields,
+  DocumentFields,
+  PlatformSection,
+} from "@/components/reference/document-fields";
+import {
+  IntentAliases,
+  IntentOverview,
+  IntentSupport,
+  IntentVocabulary,
+  QualityEngines,
+  ZonesNotApplied,
+} from "@/components/reference/pack-intent";
+import { KitFacts, KitFile, KitIntent, KitList } from "@/components/reference/kits";
 import { ErrorCodes, LoadingCodes } from "@/components/reference/error-codes";
 import { ExtensionCommands } from "@/components/reference/extension-commands";
 import { ExamplesList } from "@/components/reference/examples-list";
@@ -82,6 +95,17 @@ export function getMDXComponents(components?: MDXComponents) {
     LoadingCodes,
     DocumentFields,
     ContractFields,
+    PlatformSection,
+    IntentSupport,
+    IntentOverview,
+    QualityEngines,
+    ZonesNotApplied,
+    IntentVocabulary,
+    IntentAliases,
+    KitList,
+    KitFacts,
+    KitFile,
+    KitIntent,
     CliCommands,
     BuiltInTemplates,
     ProjectSources,

components/reference/connector-settings.tsx

@@ -3,6 +3,7 @@ import type { Connector } from "@ingestron/definitions";
 import { parse } from "yaml";
 import { readExampleFile } from "@/lib/examples";
 import { connectorEntries, shown } from "@/lib/reference";
+import { FindAndSuggest } from "./field-rows";
 import { Inline } from "./inline";
 
 interface Props {
@@ -84,6 +85,11 @@ function ConnectionField({
         <Inline text={setting.description} />
       </p>
       <ConnectionValues setting={setting} />
+      {(setting.find || setting.suggest) && (
+        <p>
+          <FindAndSuggest find={setting.find} suggest={setting.suggest} />
+        </p>
+      )}
       {example !== undefined && (
         <p>
           In the example: <code>{shown(example)}</code>.

components/reference/document-fields.tsx

@@ -1,6 +1,6 @@
 // A document kind's fields at every depth, from its JSON Schema.
 import { contractReads, type FieldInfo } from "@ingestron/definitions";
-import { documentFields } from "@/lib/reference";
+import { documentFields, packName, platformSectionFields } from "@/lib/reference";
 import { Meaning, Name } from "./field-rows";
 import { TableFrame } from "@/components/table-frame";
 
@@ -29,7 +29,16 @@ export function ContractFields() {
   );
 }
 
-function FieldTable({ label, fields }: { label: string; fields: FieldInfo[] }) {
+/** The fields of a pack's own section of the Platform, written under the pack's id.
+ * @example <PlatformSection pack="databricks" />
+ */
+export function PlatformSection({ pack }: { pack: string }) {
+  const fields = platformSectionFields(pack);
+  if (fields.length === 0) throw new Error(`The ${pack} pack's Platform section has no fields.`);
+  return <FieldTable label={`The ${packName(pack)} section of the Platform`} fields={fields} />;
+}
+
+export function FieldTable({ label, fields }: { label: string; fields: FieldInfo[] }) {
   return (
     <TableFrame label={label}>
       <table>

components/reference/error-codes.tsx

@@ -1,5 +1,6 @@
-// Every code Ingestron reports, with its meaning and fix from the code, each
-// with an anchor that problems in the editor link to.
+// Every code Ingestron reports, with its meaning, the levels it is reported
+// at and its fix from the code, each with an anchor that problems in the
+// editor link to.
 import { codeHelp, loadingCodeHelp } from "@ingestron/definitions";
 import { Inline } from "./inline";
 
@@ -24,11 +25,19 @@ export function LoadingCodes() {
   );
 }
 
+/** The levels a code is reported at, in words: "a warning", "an error or a warning". */
+export function levelWords(severities: readonly string[]): string {
+  const words = severities.map((severity) =>
+    severity === "error" ? "an error" : severity === "warning" ? "a warning" : "information",
+  );
+  return words.length > 1 ? `${words.slice(0, -1).join(", ")} or ${words.at(-1)}` : words[0]!;
+}
+
 function Codes({
   entries,
   level: Heading,
 }: {
-  entries: [string, { meaning: string; fix: string }][];
+  entries: [string, { meaning: string; fix: string; severities: readonly string[] }][];
   level: "h3" | "h4";
 }) {
   return (
@@ -37,10 +46,16 @@ function Codes({
         <section key={code}>
           <Heading id={code}>
             <code>{code}</code>
+            {help.severities.length === 0 && " (removed)"}
           </Heading>
           <p>
             <Inline text={help.meaning} />
           </p>
+          {help.severities.length > 0 && (
+            <p>
+              <strong>Reported as:</strong> {levelWords(help.severities)}.
+            </p>
+          )}
           <p>
             <strong>Fix:</strong> <Inline text={help.fix} />
           </p>

components/reference/field-rows.tsx

@@ -1,10 +1,11 @@
 // Rows of described fields: what each is, its values with their meanings, its
-// default and an example. Each row has the anchor the editor links to.
+// default, an example, and where to find a value with a suggestion, as the
+// editor's hover says them. Each row has the anchor the editor links to.
 import type { FieldInfo } from "@ingestron/definitions";
 import { anchorId, fieldPath, shown } from "@/lib/reference";
 import { Inline } from "./inline";
 
-/** The meaning column: description, allowed values with meanings, example. */
+/** The meaning column: description, allowed values with meanings, example, where to find it and a suggestion. */
 export function Meaning({ field }: { field: FieldInfo }) {
   const described = field.values ?? [];
   return (
@@ -36,6 +37,25 @@ export function Meaning({ field }: { field: FieldInfo }) {
           For example: <code>{shown(field.example)}</code>.
         </>
       )}
+      <FindAndSuggest find={field.find} suggest={field.suggest} />
+    </>
+  );
+}
+
+/** Where the owner finds a value, and what it could look like, each on a line of its own. */
+export function FindAndSuggest({ find, suggest }: { find?: string; suggest?: string }) {
+  return (
+    <>
+      {find && (
+        <span className="field-help">
+          Where to find it: <Inline text={find} />
+        </span>
+      )}
+      {suggest && (
+        <span className="field-help">
+          Suggested: <code>{suggest}</code>
+        </span>
+      )}
     </>
   );
 }